Acorn RISC PD-CD 1

home *** CD-ROM | disk | FTP | other *** search

/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / _tile / doc / manual < prev next >

Wrap

Text File | 1992-04-26 | 257.1 KB | 7,987 lines

August 1, 1990 BITFIELDS(3X) NAME bitfields - bit field manipulation library SYNOPSIS #include bitfields.f83 bitfields DESCRIPTION Allows definition and manipulation of bit fields. The bit field is described in a syntax similar to a structure with fields from the least significant bit towards the most significant bit. The bit field value is manipulated on the data stack and is therefore limited to the width of the stack, i.e., 32-bits. The kernel supports the bit field library with five functions; "b@", "b!", "f@", "<f@" and "f!". These allow high per- formance manipulation of stack oriented bit field data. The functions are also defined in forth for other environments. vocabulary bitfields ( -- ) Vocabulary for bit field definitions. Include into the search path, "context", to allow definition and usage of the bit field library. : bitfield.type ( -- ) Marks the beginning of a bit field type structure. Used in the fol- lowing form: bitfield.type <_b_i_t_f_i_e_l_d-_t_y_p_e-_n_a_m_e> ( -- ) { <_b_i_t_f_i_e_l_d-_n_a_m_e> } bitfield.end and to a create bit field variables: <bitfield-type-name> <_b_i_t_f_i_e_l_d-_v_a_r_i_a_b_l_e-_n_a_m_e> ( -- addr) The bits within the bit field are numbered from 0 to 31 starting from right (lsb) to left (msb). The <_b_i_t_f_i_e_l_d-_n_a_m_e> may be gen- erated with the words "bit", "bits", "byte", "nibble", and, "word" to define the bit field names. : bits ( width -- ) Used in the following form: <_w_i_d_t_h> bits <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width) within a bit field type definition to define field name for an arbitrary set of bits. bitfield.field bit ( -- ) Used in the following form: bit <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width) within a bit field type layout definition section to give name to a bit at the current position. The bit positions are numbered from 0 to 31 and right to left within a long number. bitfield.field nibble ( -- ) Used in the following form: nibble <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width) within a bit field type layout section definition to give name to a nibble (four bits). 1 BITFIELDS(3X) August 1, 1990 bitfield.field byte ( -- ) Used in the following form: byte <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width) within a bit field type layout section definition to give name to a byte (eight bits). bitfield.field word ( -- ) Used in the following form: word <_b_i_t_f_i_e_l_d-_n_a_m_e> ( -- pos width) within a bit field type layout section definition to give name to a word (sixteen bits). : bitfield.end ( -- ) Ends the definition of a bit field type. Will give a warning mes- sage if the last field position exceeded 32 bits. INTERNALS The _b_i_t_f_i_e_l_d_s vocabulary contains the following private definitions to allow definition of fields. : bitfield.field ( width -- ) private Utility function to create additional constant bit field type names, other than "bit", "byte", etc. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). EXAMPLES To create an object pointer bit field structure with fields for type and pointer: #include bitfields.f83 #include enumerates.f83 bitfields enumerates bitfield.type OBJECT ( -- ) 2 bits TYPE ( -- pos width) 30 bits VALUE ( -- pos width) bitfield.end Create an object pointer, access and manipulate its value: enum.type PRIMITIVE-CLASS ( -- ) enum SMALL-NUMBER ( -- enum) enum BLOCK-POINTER ( -- enum) enum OBJECT-HANDLE ( -- enum) enum PRIMITIVE ( -- enum) enum.end OBJECT x ( -- addr) SMALL-NUMBER 0 TYPE f! ( -- 0 | SMALL-NUMBER) 42 swap VALUE f! ( -- 42 | SMALL-NUMBER) 2 August 1, 1990 BITFIELDS(3X) ! NOTE The function list is sorted in logical order. The type and mode of the entries are indicated together with their parameter stack effect. The bit field definitions require a 32-bit cell size. This library may only be directly ported to other 32-bit implementations of the Forth-83 Standard. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 3 BITSETS(3X) August 1, 1990 NAME bitsets - bit vector represented sets definitions SYNOPSIS #include bitsets.f83 bitsets DESCRIPTION Allows definition and manipulation of bit vector represented sets. A set may contain maximum of 32 items as it is maintained as a stack item. All set operations are performed as logic functions; "and", "or", etc. This gives rapid manipulation of small sets. Most set operations require only one logic operation. : .bitset ( bitset -- ) immediate Used in the following form: <_b_i_t_s_e_t> .bitset <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> to display the bitset values in the following normal set notation: { <_e_n_t_r_i_e_s> } The bitset type is required to map the items back to their corresponding entries. It maintains the list of items defined in the universe set. : >item ( item -- entry) immediate Used in the following form: <_i_t_e_m> >item <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> ( item -- entry) to map an item value back to the corresponding entry given the bitset type name. The bitset type maintains the list of items defined in the universe set. : ?empty-bitset ( bitset -- bool) macro Returns "true" if the bitset is an empty set else "false". : ?map-bitset ( bitset block[ item -- bool] -- ) Conditional iterator on a bitset. The block is called for each item in the set while the block returns "false". Should the block return "true" the iterator is terminated. : ?member-bitset ( item bitset -- bool) macro Returns "true" if the item is a member of the bitset else "false". : append-bitset ( item bitset1 -- bitset2) macro Returns the result of appending the item to the bitset. : bitset.end ( -- ) Used in the following form: bitset.type <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> ( -- ) { item <_b_i_t_s_e_t-_i_t_e_m-_n_a_m_e> ( -- item) } bitset.end to terminate a bitset type definition. The bitset should not con- tain more than 32 items as a set value is represented by a 32-bit integer number (on stack). 4 August 1, 1990 BITSETS(3X) : bitset.type ( -- ) Used in the following form: bitset.type <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> ( -- ) { item <_b_i_t_s_e_t-_i_t_e_m-_n_a_m_e> ( -- item) } bitset.end to initiate the definition of a bitset type. The bitset may contain at most 32 items as a set value is represented as a 32-bit integer on stack and in memory. The bitset type may be used in the follow- ing form: <bitset-type-name> <_b_i_t_s_e_t-_v_a_r_i_a_b_l_e-_n_a_m_e> ( -- addr) to create a bitset variable (and which acts as a normal "vari- able"). vocabulary bitsets ( -- ) The bitset extension vocabulary. Include into the vocabulary search structure, "context", to allow access to this library. : difference-bitset ( bitset1 bitset2 -- bitset3) macro Returns the resulting "bitset3" after removing "bitset2" from "bitset1". constant empty-bitset ( -- bitset) Returns the empty bitset. For a bit vector representation of sets the empty set the value is zero. : intersection-bitset ( bitset1 bitset2 -- bitset3) macro Returns the intersection, "bitset3", between the sets "bitset2" and "bitset1". : item ( -- ) Used in the following form: bitset.type <_b_i_t_s_e_t-_t_y_p_e-_n_a_m_e> ( -- ) { item <_b_i_t_s_e_t-_i_t_e_m-_n_a_m_e> ( -- item) } bitset.end to create a bitset item. When the item is used it will return the item value on the parameter stack. A bitset may contain at most 32 items as each item corresponds to an unique bit in a 32-bit integer stack element. : map-bitset ( bitset block[ item -- ] -- ) Bitset iterator function. The code block is called on each item in the bitset. The code block may be created with the extension library "blocks". The block will receive the item as parameter. : remove-bitset ( item bitset1 -- bitset2) macro Returns the resulting bitset after removing the item from the bitset. : size-bitset ( bitset -- num) Returns the size of the bitset, i.e., the number of items in the set. : union-bitset ( bitset1 bitset2 -- bitset3) macro Returns the union, "bitset3", between the sets "bitset2" and 5 BITSETS(3X) August 1, 1990 "bitset1". : { ( -- ) immediate Used in the following form: { <_i_t_e_m_s> } ( -- bitset) to start the definition of a bitset. The brackets should only con- tain item entries. : } ( -- bitset) Used in the following form: { <_i_t_e_m_s> } ( -- bitset) to end a bitset definition. The brackets should only contain item entries. INTERNALS Private definitions in the _b_i_t_s_e_t_s vocabulary; : (.bitset) ( bitset bitset.type -- ) private Performs the run-time action of displaying the bitset given the mapping set of entries. Compiled by the word ".bitset". : (>item) ( item bitset.type -- entry) private Performs the run-time action of locating an item entry given its bitset value. Returns the "entry" pointer or "nil" if not found. Compiled by the word ">item". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _m_a_c_r_o_s(_3_X), _b_l_o_c_k_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entry is indicated together with the parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. 6 August 1, 1990 BITSETS(3X) AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 7 BLOCKS(3X) August 1, 1990 NAME blocks - code blocks definition library SYNOPSIS #include blocks.f83 blocks DESCRIPTION Allows definition and execution of code blocks. An alternative to pass- ing colon definitions as arguments and creating special control struc- tures. Code blocks are used by the _t_i_l_e source code library to pass parameters to iterator functions such as "map*" and "?map*". These func- tions perform the iteration over collections of data (such as lists, queues, ranges and sets) and call the code block on each element in the collection. vocabulary blocks ( -- ) Vocabulary for code block definitions. Include this library by adding the vocabulary to the search set, "context". : block[ ( -- ) immediate Used in the following form: block[ ( ... ) ... <_b_l_o_c_k-_d_e_f_i_n_i_t_i_o_n> ... ]; ( -- block) Marks the beginning of a code block. Compiles a code block until "];" and returns the address to the code block. The code block may then be executed using "call". Code blocks may contain definitions of other code blocks. Argument binding and local variables are allowed in the code block using the "locals" extension but cannot use the words "does>" and "exception>" as these require a vocabu- lary entry binding. : ]; ( -- block) immediate Used in the following form: block[ ( ... ) ... <_b_l_o_c_k-_d_e_f_i_n_i_t_i_o_n> ... ]; ( -- block) Marks the end of a code block. Returns a pointer to the code block. If the code block is generated within a colon definition the block pointer is returned at run-time. : call ( block -- ) Executes a code block. Any parameters used by the code block are passed as usual on the parameter stack. Return values are handled in the same way. INTERNALS Private definitions in the _b_l_o_c_k_s vocabulary; field +block ( addr -- block) private Field access variable to calculate the offset to an in-line block literals within a compiled section of code. 8 August 1, 1990 BLOCKS(3X) SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _c_o_m_p_i_l_e_r(_3_X). EXAMPLES An example showing how a function may return a code block which is bound to a constant and later called: : action ( flag -- block) if block[ 10 + ]; else block[ 10 - ]; then ; true action constant delayed-action 32 delayed-action call NOTE The function list is sorted in logical order. The type and mode of the entries are indicated together with their parameter stack effect. WARNING The code block may not contain the words "recurse", "tail-recurse", "does>" and "exception>" as these require an entry binding, i.e., a colon definition. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 9 BLOCKS(3X) August 1, 1990 10 August 1, 1990 COMPILER(3X) NAME compiler - tile kernel compiler support functions SYNOPSIS compiler DESCRIPTION The _c_o_m_p_i_l_e_r vocabulary of the _t_i_l_e forth kernel contains all primitives compiled by high level words for control structures and literals. The primitives are isolated to a separate vocabulary to minimize dependen- cies and increase portability. code (+loop) ( n -- ) compilation Performs the same action as "(loop)" but uses the top of stack value as the increment, "n", of the loop index. Checks if the loop limit has been exceeded. Compiled by the word "+loop". code (.") ( -- ) compilation Prints the in-line string on the current output stream. Compiled by the word "."". code (;) ( -- ) compilation Performs the run-time action of returning from a colon definition. Compiled by the word ";". code (?branch) ( flag -- ) compilation Performs the run-time action of conditionally branching in threaded code. If the "flag" is zero a branch is performed using a literal succeeding this word else the literal is skipped. The branch literal is the relative address. Compiled by the words "if", "while", "until", and "of". code (?do) ( end start -- ) compilation Performs the run-time action of initializing for a loop block if the "start" and "end" index are not equal else skips the block. Moves the two parameters, "end" and "start", to the return stack and a pointer to the relative address literal succeeding this word so that "leave" may be performed in any section of the looped block. Compiled by the word "?do". code (abort") ( flag -- ) compilation Performs the run-time action of checking the error "flag" and if non-zero, true, aborts the current computation. Uses an in-line string to display an abort message. Compiled by the word "abort"". code (does>) ( -- ) compilation Performs the run-time action of returning from the current colon definition and setting the code type of the last defined entry to be the code following "(does>)" thus giving it the right run-time action. Compiled by the word "does>". code (branch) ( -- ) compilation Performs the run-time action of branching in threaded code. Literal 11 COMPILER(3X) August 1, 1990 succeeding this word contains a relative address to the next thread. Compiled by the words "else", "again", "endof" and "repeat". code (do) ( end start -- ) compilation Performs the run-time action of initializing for a loop block. Moves the two parameters, "end" and "start", to the return stack and a pointer to the relative address literal succeeding this word so that "leave" may be performed in any section of the looped block. Compiled by the word "do". code (literal) ( -- int) compilation Pushes the in-line constant following the threaded code onto the parameter stack. Compiled by the words "literal" and "[']". code (loop) ( -- ) compilation Performs the run-time action of incrementing the loop index and checking it against the upper limit for the loop. If the index is still within the loop limit a branch is performed back to the beginning of the loop. The branch offset is stored in-line directly after the "(loop)" thread. Compiled by the word "loop". code <mark ( -- marker) compilation Marks the current position in the compilation code stream as a position for backwards branch. code <resolve ( marker -- ) compilation Allocates space for and calculates a backward branch offset. code >mark ( -- marker) compilation Allocates space for a branch offset and marks it for forward resolving. code >resolve ( marker -- ) compilation Resolves a forward branch offset. vocabulary compiler ( -- ) Vocabulary containing the compilation word set. Compiler support, compiled words and threading primitives. Include into the vocabu- lary search set, "context", to allow access to these extensions. code thread ( entry -- ) Used to create threaded code in the dictionary area. Allows code to be written without considering the threading principle. code unthread ( addr -- entry) Given a reference to threaded code returns an unthreaded entry pointer. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). 12 August 1, 1990 COMPILER(3X) EXAMPLES A simple definition of "if" and "then" with mode checking: : if ( flag -- ) compile (?branch) >mark ; compilation immediate : then ( -- ) <resolve ; compilation immediate NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. WARNING Code written using this word set is not directly portable to other forth environments. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 13 DEBUGGER(3X) August 6, 1990 NAME debugger - forth level debugger SYNOPSIS #include debugger.f83 debugger DESCRIPTION The _t_i_l_e forth debugger package. Allows basic black-box tracing of colon definitions, break on function call and profiling of function calls. The debugger is built on a general advice package so that it may easily be extended with addition debugging functions. The advice concept is a function may be asked for advice on how to handle a colon definition. The trace advice function wraps the function call in printing of the stack status and the name of the function. : *abort* ( -- ) Abort command in a break point. Will abort the break point inter- preter command loop and clear the stacks. Should only be used in a break point. : *call* ( -- ) Calls the broken function in a break point. Will not return to the break point interpreter. The program will continue. Should only be used in a break point. : *execute* ( -- ) Executes the broken funtion in a break point. Will return to the break point interpreter so that the program stack may be inves- taged. Should only be used in a break point. : *profile* ( -- ) Displays the profile information for a broken function. Should only be used in a break point. : *return* ( -- ) Returns from a break point. The break point interpreter is left. : .profile ( -- ) Scans through the definitions vocabulary, "current", and prints the available profile information for advice functions. Displays the number of calls and the name of the functions. : .s ( -- ) Displays the current parameter stack contents in the format: [ <depth> ] <bottom> \ ... \ <top> Only the top five elements of the stack are displayed. If more than five elements are available is this indicated by the depth and the prefix "...". : : ( -- ) Redefinition of "colon" to allow easy debugging of "any" code 14 August 6, 1990 DEBUGGER(3X) definitions without rewriting. : ?advice ( entry -- bool) Used in the following form: ' <_e_n_t_r_y> ?advice Verifies that the entry passed as a parameter is an advice func- tion. : advice ( action -- ) Used in the following form: ' <_a_d_v_i_c_e-_a_c_t_i_o_n> advice <_a_d_v_i_c_e-_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> Makes the parameter "action" the advice action for an advice colon definition. The colon definition is verified before the assignment is performed. The advice action should be a function which receives an advice block and performs some action on it. Resets the profile information. : break ( -- ) Used in the following form: break <_a_d_v_i_c_e-_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> to make an advice colon definition a function with a break point. An error message is given if the succeeding symbol is not of correct type. When the <advice-colon-definition> is called a break command loop is entered. A new interpreter top loop is entered. This top loop will accept any forth statement. The commands "*abort*", "*call*", "*execute*", "*profile*" and "*return*" should be used to control the execution of the broken definition. The word "*abort" will abort execution, enpty the stacks and return to the normal "interpret" top loop. The word "*call*" may be used to evoke the broken definition and continue execution. The definition will not return to the break point interpreter. The command "*exe- cute*" performs the same operation but returns to the break point interpreter so that the return value and program state may be checked before continuing. The word "*profile*" displays the pro- file information for the broken definition and last, the word "*return*" will leave the break point. : colon ( -- ) Used in the following form: colon <_a_d_v_i_c_e-_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> To make an advice colon definition a "normal" function again. An error message is given if the entry is not of correct type. vocabulary debugger ( -- ) Vocabulary containing the debugger definitions. Include into the vocabulary search set, "context", to allow access to the debugger. This vocabulary should come before "forth" in the set. : tail-recurse ( -- ) compilation immediate Redefinition of the tail recursion compilation word to make it work correctly in this context. : trace ( -- ) Used in the following form: 15 DEBUGGER(3X) August 6, 1990 trace <_a_d_v_i_c_e-_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> To make an advice colon definition a traced function. An error mes- sage is given if the succeeding symbol is not of correct type. When the <advice-colon-definition> is later called the advice function with display the name of the definition together with the stack status for both the enter and exit of the call. Profile informa- tion is also collected. INTERNALS Private definitions in the _d_e_b_u_g_g_e_r vocabulary; ptr +advice ( advice -- addr) private Access field to advice function which is called to handle the code block. The advice function is call with execute thus it is a pointer to an entry. Three predefined advice functions are avail- able for profiling, tracing and break points. ptr +block ( advice -- addr) private Access field to code block of advice colon definition. Stored as a pointer to threaded code. ptr +entry ( advice -- addr) private Access field to entry with advice block. Allows access of entry fields such as name, link, etc. Stored as a pointer to an entry. long +profile ( advice -- addr) private Access field to counter for number of function calls. Basic profil- ing information. Updated by the advice primitives. struct.type ADVICE ( -- ) private The advice structure type. Allows general handling of execution of code definitions. The structure type contains the following private fields; "+advice", "+block", and "+profile". : [advice] ( advice -- ) private Management function to allow interception of function call and cal- ling of advice function. : [break] ( advice -- ) private Primitive advice function which allows a interpreter top loop simi- lar to "interpret", the forth top loop. In this top loop the com- mands "*abort*", "*call*", "*execute*", "*profile*" and "*return*" should be used to control the execution of the advice definition. : [colon] ( advice -- ) private Primitive advice function call for normal function call and incre- ment of profiling counter. : [trace] ( advice -- ) private Primitive advice function for black-box tracing of function calls. The entry and exit of the function call are printed together with the name of the function and the status of the stack. 16 August 6, 1990 DEBUGGER(3X) SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _c_o_m_p_i_l_e_r(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X). EXAMPLES An example showing how to trace and profile a function: #include debugger.f83 forth definitions debugger : fac ( n -- n!) dup 0> if dup 1- recurse * else drop 1 then ; trace fac 5 fac . .profile NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. WARNING The debugger package will not work correctly on functions which manipu- late the return stack. An advice colon definition must always return to the advice function. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University 17 DEBUGGER(3X) August 6, 1990 S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 18 August 6, 1990 ENUMERATES(3X) NAME enumerates - enumerate variable definitions SYNOPSIS #include enumerates.f83 enumerates DESCRIPTION Allows definition of enumerate variable sets. Creates constants with the values zero and upwards. : >enum ( enum -- entry) immediate Used in the following form: <_e_n_u_m-_i_t_e_m-_v_a_l_u_e> >enum <_e_n_u_m-_t_y_p_e-_n_a_m_e> ( enum -- entry) to map an enumerate value back to its corresponding entry. If the entry is not found "nil" returned. The enumerate type maintains a pointer to the list of defined enumerates. : enum ( -- ) Used within an "enum.type" definition to declare an enumerate. enum <_e_n_u_m-_i_t_e_m-_n_a_m_e> ( -- enum) The value of the items are zero and upwards. : enum.end ( -- ) Used in the following structure: enum.type <_e_n_u_m-_t_y_p_e-_n_a_m_e> { enum <_e_n_u_m-_i_t_e_m-_n_a_m_e> ( -- enum) } enum.end to terminate a "enum.type" definition. : enum.type ( -- ) Used in the following structure: enum.type <_e_n_u_m-_t_y_p_e-_n_a_m_e> ( -- ) { enum <_e_n_u_m-_i_t_e_m-_n_a_m_e> ( -- enum) } enum.end to start the definition of an enumerate variable and identifiers. The items start with the value zero. The type may later be used to define variables: <enum-type-name> <_e_n_u_m-_v_a_r_i_a_b_l_e-_n_a_m_e> ( -- addr) The enumerate variable corresponds to a normal forth "variable" and may be accessed with the functions "@" and "!". vocabulary enumerates ( -- ) Vocabulary for enumerate definitions. Include into the search set, "context", to allow access to this language extension. INTERNALS Private definitions in the _e_n_u_m_e_r_a_t_e_s vocabulary; : (>enum) ( enum enum.type -- entry) private Performs the run-time action of locating an enumerate entry given it's value, "enum", and the enumerate type it is a member of, 19 ENUMERATES(3X) August 6, 1990 "enum.type". Compiled by the word ">enum". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). EXAMPLES The _t_i_l_e forth kernel entries have the following code types: enum.type CODES ( -- ) enum CODE ( -- enum) enum COLON ( -- enum) enum VARIABLE ( -- enum) enum CONSTANT ( -- enum) enum VOCABULARY ( -- enum) enum CREATE ( -- enum) enum USER ( -- enum) enum LOCAL ( -- enum) enum FORWARD ( -- enum) enum FIELD ( -- enum) enum EXCEPTION ( -- enum) enum.end NOTE The function list is sorted in ASCII order. The type and mode of the entry is indicated together with the parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 20 August 6, 1990 ENUMERATES(3X) 21 EXCEPTIONS(3X) August 6, 1990 NAME exceptions - tile kernel error handling functions SYNOPSIS forth DESCRIPTION The _t_i_l_e kernel word set for support of exception definition and manage- ment. Exceptions may be signaled by the environment (such as arithmetic or memory segmentation error) or raised by functions in an application. The _t_i_l_e forth virtual machine maintains exception frames. An exception frame is a copy of the state of the virtual machine when a colon defini- tion with error handling is entered. This state may be used to restore the virtual machine when an error occurs. An exception block is part of a colon definition and marked in a syntax style similar to the high level management block "does>". This block will receive the error flag (signal or exception) and the machine is restored if an error occurs. Exception blocks may be nested. A function with error handling may call functions with error handling and so on. The cost of an error handling block corresponds to the cost of saving all virtual machine registers in an exception block on the return stack. Exceptions should be used to simplify control structures where the pro- grammer is otherwise forced to mix the control structure for the algo- rithm with the control structure for the error situations. code exception ( --- ) Used in the following form: exception <_e_x_c_e_p_t_i_o_n-_n_a_m_e> ( -- exception) to define an exception symbol. An exception may be raised using: <_e_x_c_e_p_t_i_o_n-_n_a_m_e> raise The defined "exception" returns a pointer to the entry on the parameter stack when used and may be directly displayed with the word ".name". code exception> ( [signal] or [exception] -- ) compilation immediate Used within a colon definition to mark the beginning of the excep- tion section of the definition: : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... exception> ( [signal] or [exception] -- ) ... <_e_r_r_o_r-_h_a_n_d_l_i_n_g> ... ; If an error occurs or an "exception" is raised during the execution of the code definition section the control is past to the latest exception block, and the signal number or the exception is past as a parameter. The status of the stacks are restored to the situation before the execution of the most recent definition with an excep- tion block. To pass the exception upwards, to the next exception block, the function "raise" should be used. vocabulary exceptions ( -- ) 22 August 6, 1990 EXCEPTIONS(3X) Vocabulary containing the exception management definitions. Allows definitions of forth level capturing of errors. Uses a syntax style similar Ada to make the beginning of an exception section within a colon definition. Include into the vocabulary search structure, "context", to allow access of these extensions. code raise ( [signal] or [exception] -- ) Activates a exceptions handler with signal identification number or an exception symbol. If an exception frame exists the virtual machine is restored to this state and resumed. The default action taken if no exception block is available is abort with a message about the task, and the name of the signal or exception. Signals are generated from the run-time environment. INTERNALS The following words of the exception extension are mainly used to imple- ment the error handling mechanism. code (exception;) ( -- ) compilation Unlinks the current exception frame from the return stack and returns from a colon definition. Compiled by the word "exception>". code (exception>) ( addr -- ) compilation Builds an exception frame on the return stack and jumps to the address given as a parameter, "addr". A colon definition with an exception block will have a "code" field with a pointer to code section with this word. The virtual machine will push a pointer to the parameter field, "addr", and call the exception section. code (exceptionunlink;) ( -- ) compilation Unlinks the exception frame and argument frame from the stacks and returns from the colon definitions. Compiled by the word "excep- tion>" when a local frame has been used. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). EXAMPLES An example showing how to redefine the arithmetic division operation for exception and retry: exceptions exception zero-division ( -- exception) : div ( x y -- z) dup 0= if zero-division raise else / then ; : use-div ( x y -- z) div exception> ( x y exception -- ) case zero-division of drop endof 23 EXCEPTIONS(3X) August 6, 1990 raise ( pass exception upwards) endcase NOTE The function list is sorted in ASCII order. The type and mode of the entry is indicated together with the parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 24 August 1, 1990 FLOAT(3X) NAME float - tile kernel floating point arithmetic functions SYNOPSIS float DESCRIPTION The _t_i_l_e forth kernel extends the Forth-83 Standard with arithmetic functions for 32-bit floating point numbers. When the "float" vocabulary is used floating point numbers will be recognized by "interpret", the kernel compiler and interpreter. The function "?float" is the "float" recognizer function. code ?float ( str -- [str false] or [f1 true]) recognizer Given a null-terminated string, "str", scans for a 32-bit floating point number. Returns the value and "true" else the string and "false". This word is the "float" vocabulary literal recognizer function. The function will also recognize the symbols "Infinity", "-Infinity", and "NaN" (not a number) which are defined by the IEEE single precision floating point number system. code 1/f ( f1 -- f2) "f2" is the 32-bit floating point result of dividing one by "f1". code f* ( f1 f2 -- f3) "f3" is the 32-bit floating point product of "f1" and "f2". code f+ ( f1 f2 -- f3) "f3" is the 32-bit floating point arithmetic sum of "f1" and "f2". code f- ( f1 f2 -- f3) "f3" is the 32-bit floating point result of subtracting "f2" from "f1". code f. ( f1 -- ) The 32-bit floating point number "f1" is displayed in the standard format on the current output stream. code f/ ( f1 f2 -- f3) "f3" is the 32-bit floating point number the quotient of "f1" divided by the divisor "f2". An error condition results if the divisor is zero. code f>i ( f1 -- i1) The 32-bit floating point number "f1" is converted to a 32-bit integer. vocabulary float ( -- ) The floating pointer number extension vocabulary. Include into the vocabulary search set, "context", to allow access to these exten- sions. code fnegate ( f1 -- f2) 25 FLOAT(3X) August 1, 1990 "f2" is the negated value of the floating point value "f1", i.e., the difference of zero less "f1". code i>f ( i1 -- f1) The 32-bit integer "i1" is converted to a 32-bit floating point number, "f1". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 26 April 11, 1991 FORTH(3X) NAME forth - forth-83 standard word set and tile forth kernel extensions SYNOPSIS forth DESCRIPTION The required word set of Forth-83 Standard excluding the block file word set and the _t_i_l_e forth kernel extensions. Each "word" (function, pro- cedure, variable, etc) is described with its stack action, parameters, and return values and its code type. The format of the glossary list is: <type> <name> ( <stack-effect> ) [ <mode> ] The <stack-effect> describes the parameter and return values for the word in the following format: ( <arguments> -- <returns>) The arguments and return values are given from left to right with the deepest stack value first. Symbolic names are often used for the argu- ments while the return values are often only described by data type. The optional <mode> may define how the word is interpreted and when it is visible. The mode "immediate" marks the word as always executed. The mode "execution" reduces the words visibility to only execution, i.e., interpretation, mode. The mode "compilation" reduces the words visibil- ity to only compilation mode. Last, the mode "private" marks the words as only visible in the vocabulary where it is defined. Additional modes are added by other _t_i_l_e forth extensions. The list of required words in the Forth-83 Standard are described in the following sub-sections; "Stack Manipulation", "Memory Access", "Logic", "Arithmetic", "Comparison", "Numeric Conversion", "Control Structures", "Terminal Input/Output", "Interpreter", "Vocabulary", and "Defining Words". Each sub-section is sorted in ASCII order. Stack Manipulation The Forth-83 Standard parameter and return stack manipulation functions. The _t_i_l_e forth kernel also supports the double number stack manipulation extension. code -rot ( x y z -- z x y) The top three stack entries are rotated, forcing the top to become the deepest of the three. code 2>r ( x y -- ) compilation Double "to-r". "x" and "y" are transferred to the return stack. code 2drop ( x y -- ) Double "drop". "x" and "y" are dropped. code 2dup ( x1 y1 -- x1 y1 x1 y1) Double "dup". The first pair is copied. code 2over (x1 y1 x2 y2 -- x1 y1 x2 y2 x1 y1) 27 FORTH(3X) April 11, 1991 Double "over". The second pair is copied. code 2r> ( -- x y) compilation Double "from-r". "x" and "y" are removed from the return stack and transferred to the data stack. code 2rot ( x1 y1 x2 y2 x3 y3 -- x2 y2 x3 y3 x1 y1) Double "rot". The three pairs change places. code 2swap ( x1 y1 x2 y2 -- x2 y2 x1 y1) Double "swap". The two pairs change places. code >r ( x -- ) compilation Transfer "x" to the return stack. code ?dup ( x -- [x x] or [x]) Duplicate "x" if it is non-zero. code depth ( -- +n) "+n" is the number of values contained in the data stack before "+n" was placed on the stack. code drop ( x -- ) "x" is removed from the stack. code dup ( x -- x x) Duplicate "x". code nip ( x y -- y) The second stack element "x" is removed. code over ( x y -- x y x) A copy of "x" is made and moved over "y". code pick ( +n -- x) "x" is a copy of the "+n"-th stack element, not counting "+n" itself. [0..depth-1] "0 pick" is equivalent to "dup" "1 pick" is equivalent to "over" code r> ( -- x) compilation "x" is removed from the return stack and transferred to the data stack. code r@ ( -- x) compilation "x" is a copy of the top of the return stack. code roll ( +n -- ) The "+n"-th stack value, not counting "+n" itself is first removed and then transferred to the top of the stack, moving the remaining values into the vacated position. The parameter should be in the interval: [0..depth-1]. "0 roll" is a null operation "1 roll" is equivalent to "swap" 28 April 11, 1991 FORTH(3X) "2 roll" is equivalent to "rot" code rot ( x y z -- y z x) The top three stack entries are rotated, bringing the deepest to the top. code swap ( x y -- y x) The top two stack entries are exchanged. code tuck ( x y -- y x y) A copy of "y" is tucked under "x". Memory Access The Forth-83 Standard memory and data access word set. The _t_i_l_e forth kernel extends the Forth-83 Standard with additional access functions for bit testing and bit field access. All access to memory is achieved through this word set. code ! ( 32b addr -- ) The postfix assignment operator. Store "32b" at "addr". code +! ( x1 addr -- ) "x1" is added to the value at "addr" using the convention for "+". The value at "addr" is assumed to be of size "cell". The sum replaces the original value at "addr". code -match ( addr1 addr2 n -- bool) Matches the strings at address "addr1" and "addr2" of length "n" at the parameter addresses. Returns "false" if the strings are equal else "true". If the length "n" is zero the function will return "true". code -trailing ( addr +n1 -- addr +n2) The character counter "+n1" of a text string beginning at "addr" is adjusted to exclude trailing spaces. If "+n1" is zero, then "+n2" is zero. If the entire string consists of spaces, then "+n2" is zero. code <c@ ( addr -- 8b) "8b" is the value at "addr". The value is sign extended to the stack (cell) width. code <f@ ( x p w -- y) Field access within a 32-bit quantity. "y" are the bits within "x" at position "p" and with a bit field width, "w". Bits positions are counted from right to left starting with zero. A field is defined from a position and upwards. The result "y" is sign extended. code <w@ ( addr -- 16b) "16b" is the value at "addr". The value is sign extended to the stack (cell) width. code @ ( addr -- 32b) 29 FORTH(3X) April 11, 1991 "32b" is the value at "addr". Primary variable value access func- tion. code b! ( x y p -- z) Returns "z", the result of setting the bit at position "p" in "y" according to the value of "x". The bit is set to zero if "x" is zero else one. code b@ ( x p -- y) Returns "true" if the bit a position "p" in "x" is one else "false". code bounds ( addr1 n -- addr2 addr1) Converts vector address and size to boundary address suitable for a "do"-loop. "addr2" is the end address of the vector, i.e., the sum of "addr1" and "n". code c! ( 8b addr -- ) The postfix assignment operator. Store "8b" at "addr". code c@ ( addr -- 8b) "8b" is the value at "addr". The value is not sign extended. code cmove ( addr1 addr2 u -- ) Move the "u" bytes at address "addr1" to "addr2". The byte at "addr1" is moved first, proceeding toward high memory. If "u" is zero nothing is moved. code cmove> ( addr1 addr2 u -- ) Move the "u" bytes at address "addr1" to "addr2". The move begins by moving the byte at ("addr1"+"u"-1) to ("addr2"+"u"-1) and proceeds to successively lower addresses for "u" bytes. If "u" is zero nothing is moved. Useful for sliding a string towards higher addresses. code count ( addr1 -- addr2 +n) "addr2" is "addr1"+1 and "+n" is the length of the counted string at "addr1". The byte "addr1" contains the byte count "+n". Range of "+n" is [0..255]. code f! ( x y p w -- z) Inserts the value of "x" into "y" at the bit field which is defined by the position "p" and with the width "w". The value "x" is shifted and masked into "y" to form the result "z". code f@ ( x p w -- y) Field access within a 32-bit quantity. "y" are the bits within "x" at position "p" and with a bit field width, "w". Bits positions are counted from right to left starting with zero. A field is defined from a position and upwards. code fill ( addr u 8b -- ) "u" bytes of memory beginning at "addr" are set to "8b". No action is taken is "u" is zero. 30 April 11, 1991 FORTH(3X) code w! ( 16b addr -- ) The postfix assignment operator. Store "16b" at "addr". code w@ ( addr -- 16b) "16b" is the value at "addr". The value is not sign extended. Logic The Forth-83 Standard logic functions. The _t_i_l_e forth kernel extends the basic function set with boolean constants and a boolean conversion func- tion. All logic functions manipulate their parameters bit-by-bit. code and ( 32b1 32b2 -- 32b3) "32b3" is the bit-by-bit logical and of "32b1" and "32b2". code boolean ( n -- bool) Maps numerical value to a boolean value, "true" or "false". Non- zero values are mapped to "true" and zero to "false". constant false ( -- 0) The constant "false" represented by the value zero. code or ( 32b1 32b2 -- 32b3) "32b3" is the bit-by-bit inclusive-or of "32b1" with "32b2". code not ( 32b1 -- 32b2) "32b2" is the one's complements of "32b1". constant true ( -- -1) The constant "true" represented by the value minus one. code xor ( 32b1 32b2 -- 32b3) "32b3" is the bit-by-bit exclusive-or of "32b1" with "32b2". Arithmetic The Forth-83 Standard arithmetic word set. The _t_i_l_e forth kernel extends the Forth-83 Standard with arithmetic functions for shifting and addi- tional numeric constants. Double number width arithmetic function such as "d+" and "dnegate" are not implemented as _t_i_l_e forth is a 32-bit implementation. Arithmetic errors are caught by the _t_i_l_e forth kernel and passed to the application as signals. An exception block may be used to catch the signal. code * ( w1 w2 -- w3) "w3" is the least-significant 32 bits of the arithmetic product of "w1" times and "w2". code */ ( w1 w2 w3 -- w4) "w1" is first multiplied by "w2" producing an intermediate 32-bit result. "w4" is the floor of the quotient of the intermediate 32- bit result divided by the divisor "w3". The product of "w1" times "w2" is maintained as an intermediate 32-bit result for greater precision then the otherwise equivalent sequence: "w1 w2 * w3 /". 31 FORTH(3X) April 11, 1991 An error condition results if the divisor is zero and an exception is raised. code */mod ( w1 w2 w3 -- w4 w5) "w1" is first multiplied by "w2" producing an intermediate 32-bit result. "w4" is the remainder and "w5" is the floor of the quotient of the intermediate 32-bit result divided by the divisor "w3". A 32-bit intermediate product is used as for "*/". "w4" has the same sign as "w3" or is zero. An error condition results if the divisor is zero and an exception is raised. code + ( w1 w2 -- w3) "w3" is the arithmetic sum of "w1" and "w2". code - ( w1 w2 -- w3) "w3" is the result of subtracting "w2" from "w1". constant -1 ( -- -1) Constant minus one. constant -2 ( -- -2) Constant minus two. constant -4 ( -- -4) Constant minus four. code / ( w1 w2 -- w3) "w3" is the floor of the quotient of "w1" divided by the divisor "w2". An error condition results if the divisor is zero. code /mod ( w1 w2 -- w3 w4) "w3" is the remainder and "w4" the floor of the quotient of "w1" divided by the divisor "w2". "w3" has the same sign as "w2" or is zero. An error condition results if the divisor is zero and an exception is raised. constant 0 ( -- 0) Constant zero. constant 1 ( -- 1) Constant one. code 1+ ( w1 -- w2) "w2" is the result of adding one to "w1" according to the operation of "+". code 1- ( w1 -- w2) "w2" is the result of subtracting one to "w1" according to the operation of "-". constant 2 ( -- 2) Constant two. code 2* ( n1 -- n2) 32 April 11, 1991 FORTH(3X) "n2" is the result of arithmetically shifting "n1" left one bit. The sign is included in the shift and remains unchanged. code 2+ ( w1 -- w2) "w2" is the result of adding two to "w1" according to the operation of "+". code 2- ( w1 -- w2) "w2" is the result of subtracting two to "w1" according to the operation of "-". code 2/ ( n1 -- n2) "n2" is the result of arithmetically shifting "n1" right one bit. The sign is included in the shift and remains unchanged. constant 4 ( -- 4) Constant four. code << ( n1 n2 -- n3) "n3" is the result of logically shifting "n1" left "n2" steps. code >> ( n1 n2 -- n3) "n3" is the result of logically shifting "n1" right "n2" steps. code abs ( n -- u) "u" is the absolute value of "n". code max ( n1 n2 -- n3) "n3" is the greater of "n1" and "n2" according to the operation of ">". code min ( n1 n2 -- n3) "n3" is the lesser of "n1" and "n2" according to the operation of "<". code mod ( n1 n2 -- n3) "n3" is the remainder after dividing "n1" by divisor "n2". "n3" has the same sign as "n2" or is zero. An error condition results if the divisor is zero or if the quotient falls outside of the numeri- cal range. code negate ( n1 -- n2) "n2" is the two's complement of "n1", i.e., the difference of zero less "n1". constant nil ( -- 0) Constant for a nil pointer. code um* ( u1 u2 -- u3) "u3" is the unsigned product of "u1" times "u2". All values and arithmetic are unsigned. code um/mod ( u1 u2 -- u3 u4) "u3" is the remainder and "u4" is the floor of the quotient after 33 FORTH(3X) April 11, 1991 dividing "u1" by the divisor "u2". All values and arithmetic are unsigned. An error condition results if the divisor is zero or if the quotient lies outside the numerical range. Comparison The Forth-83 Standard comparison word set. The _t_i_l_e forth kernel extends the standard with an integer range test function. The kernel does not implement double number comparison functions. Boolean values "true" and "false" are represented with "-1" and "0". code 0< ( n -- bool) Returns "true" if "n" is less than zero (negative). code 0= ( w -- bool) Returns "true" if "w" is zero. code 0> ( n -- bool) Returns "true" if "n" is greater than zero. code < ( n1 n2 -- bool) Returns "true" if "n1" is less than "n2". code = ( w1 w2 -- bool) Returns "true" if "w1" is equal to "w2" code > ( n1 n2 -- bool) Returns "true" if "n1" is greater than "n2" code ?within ( value lower upper -- bool) Tests if the parameter "value" is within the range "lower" to "upper". Returns "true" if within the range else "false". code u< ( u1 u2 -- bool) Returns "true" if "u1" is less than "u2". Numeric Conversion The Forth-83 Standard numeric conversion functions. The _t_i_l_e forth ker- nel extends the standard with string to number converter, and general number literal recognition. code # ( +d1 -- +d2 ) The remainder of "+d1" divided by the value of "base" is converted to a ASCII character and appended to the output string toward lower memory addresses. "+d2" if the quotient and is maintained for further processing. Typically used between "<#" and "#>". code #> ( x -- addr +n) Pictured numeric output conversion is ended dropping "x". "addr" is the address of the resulting output string. "+n" is the number of characters in the output string. "addr" and "+n" together are suitable for "type". 34 April 11, 1991 FORTH(3X) code #s ( +x -- 0) "+x" is converted appending each resultant character into the pic- tured numeric output string until the quotient is zero. A single zero is appended to the output string if the number was initially zero. Typically used between "<#" and "#>". code <# ( x -- ) Initialize pictured numeric output conversion. The words: "<# # #s hold sign #>" can be used to specify the conversion of a number into an ASCII text string stored in right-to-left order. code ?number ( str -- [n true] or [str false]) recognizer Convert a string of character to a number using the current "base". If the conversion is not possible the string is returned with a "false" flag indicating that the conversion failed otherwise the conversion value, the number, and a "true" flag is returned. variable base ( -- addr) The address of a variable containing the current numeric conversion radix. code binary ( -- ) Set the input-output numeric conversion "base" to 2. code convert ( +d1 addr1 -- +d2 addr2) "+d2" is the result of converting the characters within the text beginning at "addr1"+1 into digits, using the value of "base", and accumulating each into "+d1" after multiplying "+d1" by the value of "base". Conversion continues until an inconvertible character is encountered. "addr2" is the location of the first inconvertible character. code decimal ( -- ) Set the input-output numeric conversion "base" to 10. code hex ( -- ) Set the input-output numeric conversion "base" to 16. code hold ( char -- ) "char" is inserted into a pictured numeric output string. Typi- cally used between "<#" and "#>". code octal ( -- ) Set the input-output numeric conversion "base" to 8. code sign ( n -- ) If "n" is negative, an ASCII "-" (minus sign) is appended to the pictured numerical output string. Typically used between "<#" and "#>". Control Structures The Forth-83 Standard control flow word set. The _t_i_l_e forth kernel extends the basic set of control structures with environment arguments 35 FORTH(3X) April 11, 1991 access, conditional compilation, case structure, additional loop con- structs, and recursion words. code #else ( -- ) immediate Used in the following form: <_f_l_a_g> #if <_t_r_u_e-_p_a_r_t> #else <_e_l_s_e-_p_a_r_t> #then Marks the beginning of a "else"-part of a conditional code section. code #if ( flag -- ) immediate Used in the following form: <_f_l_a_g> #if <_t_r_u_e-_p_a_r_t> [ #else <_f_a_l_s_e-_p_a_r_t> ] #then Marks the beginning of a conditional code section. The else section is optional. code #ifdef ( -- ) immediate Used in the following form for testing if a symbol already is available: #ifdef <_n_a_m_e> <_t_r_u_e-_p_a_r_t> [ #else <_f_a_l_s_e-_p_a_r_t> ] #then If <_n_a_m_e> is available in the current search chain "context" the true section of code is executed or compiled according to mode else the optional false section. code #ifundef ( -- ) immediate Used in the following form: #ifundef <_n_a_m_e> <_t_r_u_e-_p_a_r_t> [ #else <_f_a_l_s_e-_p_a_r_t> ] #then Performs the same function as "#ifdef" but the true section is exe- cuted if the symbol is not available in the current search chain. code #then ( -- ) immediate Used in the following form: <_f_l_a_g> #if <_t_r_u_e-_p_a_r_t> [ #else <_f_a_l_s_e-_p_a_r_t> ] #then Marks the end of a conditional code section. code +loop ( n -- ) immediate compilation "n" is added to the loop index. If the new index was incremented across the boundary between limit-1 and limit then the loop is ter- minated and the loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding "do". "+loop" is not available outside a colon defin- ition. code ?do ( w1 w2 -- ) immediate compilation Used in the following forms: ?do ... { i | leave } ... loop or ?do ... { i | leave } ... +loop Begins a checked entry loop which terminates based on control parameters. The loop index begins at "w2", and terminates based on the limit "w1". See "loop" and "+loop" for details on how the loop is terminated. If "w1" and "w2" are equal the loop section is skipped. code abort ( -- ) Clears the data stack and performs the function of "quit". No 36 April 11, 1991 FORTH(3X) message is displayed. code abort" ( flag -- ) immediate compilation Used in the following form: <_f_l_a_g> abort" <_a_b_o_r_t-_m_e_s_s_a_g_e> " When later executed, if "flag" is true the <_a_b_o_r_t-_m_e_s_s_a_g_e> delim- ited by close quote, is displayed and then a system dependent error abort sequence, including the function "abort", is performed. If "flag" is false, the flag is dropped and execution continues. The blank following abort" is not part of the <_a_b_o_r_t-_m_e_s_s_a_g_e>. code again ( -- ) immediate compilation Used in the following form to compile an eternal loop: begin ... again The loop construct may only be left by an "abort" or an "exit" word in the code section of the loop. code argc ( -- num) Returns the number of arguments passed from the environment. The first argument is always the name of the application: "forth" or the name of the start symbol. code argv ( n -- str) Given an index returns the corresponding argument string. The "string" vocabulary words may be used for process an argument string. code begin ( -- ) immediate compilation Used in the following forms: begin ... <_f_l_a_g> while ... repeat or begin ... <_f_l_a_g> until or begin ... again "begin" marks the start of a word sequence for repetitive execu- tion. A "begin-while-repeat" loop will repeat until <_f_l_a_g> is false. "begin-until" loop will be repeated until <_f_l_a_g> is true and "begin-again" will repeat until "abort"-ed. The words after "until" and "repeat" will be executed when either loop is finished. code bye ( -- ) Leaves the interaction level and exits to the outer support system (if any). code case ( value -- ) immediate compilation Used in the following form: case <_c_a_s_e-_s_t_r_u_c_t_u_r_e> { <_d_e_f_a_u_l_t-_p_a_r_t> } endcase to mark the beginning of a case structure which should contain a one or several case statements: <_c_a_s_e-_v_a_l_u_e> of <_c_a_s_e-_p_a_r_t> endof The code section after the last case value part will receive "value" as a parameter thus a default behavior is easy implemented. The default section may only copy this value as "endcase" is an implicit "drop". 37 FORTH(3X) April 11, 1991 code do ( w1 w2 -- ) immediate compilation Used in the following forms: do ... { i | leave } ... loop or do ... { i | leave } ... +loop Begins a loop which terminates based on control parameters. The loop index begins at "w2", and terminates based on the limit "w1". See "loop" and "+loop" for details on how the loop is terminated. The loop is always executed at least once. code else ( -- ) immediate compilation Used in the following form: <_f_l_a_g> if <_t_r_u_e-_p_a_r_t> else <_f_a_l_s_e-_p_a_r_t> then in a conditional structure to mark the beginning of the false sec- tion. This section is executed when the <_f_l_a_g> is "false". The true section is then skipped. code endcase ( -- ) immediate compilation Used in the following form: case <_c_a_s_e-_s_t_r_u_c_t_u_r_e> { <_d_e_f_a_u_l_t-_p_a_r_t> } endcase to mark the end of a case structure. code endof ( -- ) immediate compilation Used in the following form: <_c_a_s_e-_v_a_l_u_e> of <_c_a_s_e-_p_a_r_t> endof to mark the end of a cast value structure. code execute ( addr -- ) The word definition indicated by "addr" is executed. An error con- dition exists if "addr" is not a compilation address. code exit ( -- ) compilation Compiled within a colon definition such that when executed, the colon definition returns control to the definition that passed con- trol to it by returning control to the return point on the top of the return stack. An error condition exists if the top of the return stack does not contain a valid return point. May not be used within a "do-loop" or "do-+loop" or an "exception"-block. code i ( -- w) compilation "w" is a copy of the current loop index. May only be used in the form: do ... { i | leave } ... loop or do ... { i | leave } ... +loop "i" is not visible outside a colon definition, i.e., when text interpreting and should only be used within a loop-block. code if ( flag -- ) immediate compilation Used in the following form: <_f_l_a_g> if <_t_r_u_e-_p_a_r_t> [ else <_e_l_s_e-_p_a_r_t> ] then If "flag" is true, the words following "if" are executed and the words following "else" until just after "then" are skipped. The "else" part is optional. If "flag" is false, words from "if" 38 April 11, 1991 FORTH(3X) through "else", or from "if" through "then" (when no "else" is used) are skipped. code j ( -- w) compilation "w" is a copy of the index of the next outer loop. May only be used within a nested "do-loop" or "do-+loop" in the form: do ... do ... { i | j | leave } ... loop ... loop "j" is not visible outside a colon definition, i.e., when text interpreting. code leave ( -- ) compilation Transfers execution to just beyond the next "loop" or "+loop". The loop is terminated and the loop control parameters are discarded. May only be used in the following forms: do ... { i | leave } ... loop or do ... { i | leave } ... +loop "leave" may appear within other control structures which are nested within the "do-loop" structure. More than one "leave" may appear within a do-loop. code loop ( -- ) immediate compilation Increments the "do-loop" index by one. If the new index was incre- mented across the boundary between limit-1 and limit the loop is terminated and the loop control parameters are discarded. When the loop is not terminated, execution continues to just after the corresponding "do". code of ( value -- ) immediate compilation Used in the following form: <_c_a_s_e-_v_a_l_u_e> of <_c_a_s_e-_p_a_r_t> endof within a case structure to define a value case. code quit ( -- ) Clears the return stack, sets interpret state, accepts new input from the current input device, and begins text interpretation. No messages is displayed. code recurse ( -- ) immediate compilation Used within a definition to make a recursive call to the current definition. code repeat ( -- ) immediate compilation Used in the following form: begin ... <_f_l_a_g> while ... repeat At execution-time, "repeat" continues execution to just after the corresponding "begin". code tail-recurse ( -- ) immediate compilation Used within a definition to create a recursive call to the current definition without saving return status. This is an efficient way of generating iterative forms as tail recursive calls may be per- formed any number of times within a definition and corresponds to a branch to the beginning of the definition. 39 FORTH(3X) April 11, 1991 code then ( -- ) immediate compilation Used in the following form: <_f_l_a_g> if <_t_r_u_e-_p_a_r_t> [ else <_e_l_s_e-_p_a_r_t> ] then Marks the end of a conditional statement "if-else-then". code until ( flag -- ) immediate compilation Used in the following form: begin ... <_f_l_a_g> until Marks the end of a "begin-until" loop which will terminate based on "flag". If "flag" is true, the loop is terminated. If "flag" is false, execution continues to just after the corresponding "begin". code while ( flag -- ) immediate compilation Used in the following form: begin ... <_f_l_a_g> while ... repeat Selects conditional execution based on "flag". When "flag" is true, execution continues to just after the "while" through to the "repeat" which then continues execution to just after the "begin". When "flag" is false, execution continues to just after the "repeat", exiting the control structure. Terminal Input/Output The Forth-83 Standard terminal interaction functions. The _t_i_l_e forth kernel extends the basic set of input and output functions with field format output and access of the current input source file name and the current line number count. code . ( n -- ) The absolute value of "n" is displayed in a free field format with a leading minus sign if "n" is negative. A space is emit after the number. code ." ( -- ) immediate compilation Used in the following form within a code definition: <_o_u_t_p_u_t-_s_t_r_i_n_g> " Later execution will display the characters <_o_u_t_p_u_t-_s_t_r_i_n_g> up to but but including the delimiter (close-quote). The blank following the "." " is not part of the <_o_u_t_p_u_t-_s_t_r_i_n_g> but the word separa- tor. code .( ( -- ) immediate Used in the following form: .( <_o_u_t_p_u_t-_c_o_m_m_e_n_t> ) The characters <_o_u_t_p_u_t-_c_o_m_m_e_n_t> up to but not including the delim- iter (closing-parenthesis) are displayed. The blank following ".(" is not part of the <_o_u_t_p_u_t-_c_o_m_m_e_n_t>. code .s ( -- ) Displays the current parameter stack contents in the format: [ <depth> ] <bottom> \ ... \ <top> code ascii ( -- char) immediate Used in the following form: 40 April 11, 1991 FORTH(3X) ascii <_c_h_a_r_a_c_t_e_r> ( -- char) to create a character literal. code cr ( -- ) Emits ASCII characters carriage-return and line-feed. code emit ( x -- ) The least-significant 7-bit ASCII character is displayed. code expect ( addr +n -- ) Receive characters and store each into memory. The transfer begins at "addr" proceeding towards higher addresses one byte per charac- ter until either a "return" is received or until "+n" characters have been transferred. No more than "+n" characters will be stored. The "return" is not stored into memory. No characters are received or transferred if "+n" is zero. All characters actually received and stored into memory will be displayed, with "return" displaying as a space. The actual number of characters received is stored in the variable "span". code key ( -- x) The next extended ASCII character received. All valid ASCII charac- ters can be received. Control characters are not processed by the system for any editing purpose. Characters received by "key" are displayed in _t_i_l_e forth due to interaction with the operating sys- tem. code line ( -- +n) Returns the current number of lines received from the current input "source". code r. ( n w -- ) The absolute value of "n" is displayed in a field format of width "w" with a leading minus sign if "n" is negative. code source ( -- str) Returns the name string of the fully path expanded current file name. "nil" is returned if the current source is the standard input device. code space ( -- ) Displays an ASCII space, i.e., emits an ASCII space character code. code spaces ( +n -- ) Displays "+n" ASCII spaces. Nothing is displayed if "+n" is zero. variable span ( -- addr) The address of a variable containing the count of characters actu- ally received and stored by the last execution of "expect". code type ( addr +n -- ) "+n" characters are displayed from memory beginning with the char- acter at "addr" and continuing through consecutive addresses. Noth- ing is displayed if "+n" is zero. 41 FORTH(3X) April 11, 1991 code u. ( u -- ) "u" is displayed as an unsigned number in a free-field format. code u.r ( u w -- ) "u" is displayed as an unsigned number in a field format with width "w". Interpreter The Forth-83 Standard interpreter functions. The _t_i_l_e forth kernel extends the interpreter word set with functions for loading of source files, library directory paths and mode marking of vocabulary entries. The additional modes allow marking with concern to the interpreter state and visibility across vocabularies. code #include ( -- ) Used in the following form to load source files: #include <_f_i_l_e-_n_a_m_e> The <_f_i_l_e-_n_a_m_e> is any string until a white space character. The file is located using the current set of paths defined by the environment variables $TILEPATH, $PWD, and $HOME. If the file has already been included the operation is ignored. The kernel main- tains a list of all loaded files with their fully expanded names. code #path ( -- ) Used in the following form to define a file search path: #path <_p_a_t_h-_n_a_m_e> The input function, "#include", uses a set of path to allow shorter file names to be used and support source code libraries. The ini- tial set of paths are defined by the environment variables $PWD, $TILEPATH, and $HOME. code ( ( -- ) immediate Used in the following form: ( <_c_o_m_m_e_n_t-_s_t_r_i_n_g> ) The characters enclosed by the delimiter ")" are considered com- ments. Comments are not otherwise processed. The blank following "(" is not part of the comment string. The number of characters in the comment string may be from zero to the number of characters remaining in the input stream up to the closing parenthesis. code , ( x -- ) Allocates space for "x" then store value at "here cell -". code .name ( addr1 -- ) Given the compilation address "addr1" of an entry prints the name of the entry. code >body ( addr1 -- addr2) "addr2" is the parameter field address corresponding to the compi- lation address "addr1". code ?compile ( -- ) compilation Used in the following form: 42 April 11, 1991 FORTH(3X) ?compile <_c_o_m_p_i_l_e_d-_e_n_t_r_y> to compile an entry at run-time. Considers the compilation state at run-time. If the state is compiling then performs the same action as "compile" else does nothing and the succeeding word is executed and not compiled. code [ ( -- ) immediate Sets interpret (execution) state. The text from the input stream is subsequently interpreted. Typically usage see "literal". code [compile] ( -- ) immediate compilation Used in the following form: [compile] <_c_o_m_p_i_l_e_d-_e_n_t_r_y> Forces compilation of the succeeding word. This allows compilation of an "immediate" word when it would otherwise have been executed. If the entry is not found an error message is given. code \ ( -- ) immediate Used in the following form: \ <_c_o_m_m_e_n_t-_s_t_r_i_n_g> Comment terminate by end of line (carriage return). code ] ( -- ) Sets compilation state. The text from the input stream is subse- quently compiled. code allot ( w -- ) Allocated "w" bytes from the dictionary. The address to the next available dictionary location is updated accordingly. code align ( -- ) Align dictionary pointer to nearest cell boundary. code cell ( -- bytes) Returns the number of bytes per cell. Four bytes for a 32-bit Forth. code cell+ ( n -- m) Returns the result, "m", of incrementing "n" by "cell". code cells ( n -- m) Returns the given value, "n", in cells. The result of "n" times "cell". code compilation ( -- ) Used in the following form: : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; compilation Marks the most recently created dictionary entry as a word which is only available in compilation mode. code compile ( -- ) compilation Typically used in the following form: : <_n_a_m_e> ... compile <_c_o_m_p_i_l_e_d-_e_n_t_r_y> ... ; immediate compilation When <_n_a_m_e> is executed, the compilation address compiled for 43 FORTH(3X) April 11, 1991 <_c_o_m_p_i_l_e_d-_e_n_t_r_y> is compiled and not executed. <_n_a_m_e> is typically "immediate" and "compilation", and <_c_o_m_p_i_l_e_d-_e_n_t_r_y> is typically not an immediate word. code compiling ( -- bool) Returns the contents of the state variable as this variable should not be altered by other than system functions. code does> ( addr -- ) immediate compilation Defines the run-time action of a word created by a high-level defining word. Used in the following form: : <_d_e_f_i_n_i_n_g> ( ... ) ... <_c_r_e_a_t_e-_d_e_f_i_n_i_t_i_o_n> ... does> ( addr -- ...) ... <_r_u_n-_t_i_m_e-_d_e_f_i_n_i_t_i_o_n> ... ; and then <defining> <_n_a_m_e> (...) where <_c_r_e_a_t_e-_d_e_f_i_n_i_t_i_o_n> is "create" or any user defined word which executes "create", and allocated memory. Marks the termina- tion of the defining part of the defining word <_d_e_f_i_n_i_n_g> and then begins the definition of the <_r_u_n-_t_i_m_e-_d_e_f_i_n_i_t_i_o_n> for words that will later be defined by <_d_e_f_i_n_i_n_g>. When <_n_a_m_e> is later executed, the parameter field address, "addr", of <_n_a_m_e> is pushed on the parameter stack and then the sequence of words between "does>" and ";", the <_r_u_n-_t_i_m_e-_d_e_f_i_n_i_t_i_o_n>, is executed. Multi-levels of high- level definitions are possible, i.e., "create-does>" may be used multiple times within the <_r_u_n-_t_i_m_e-_d_e_f_i_n_i_t_i_o_n>. code execution ( -- ) Used in the following form: : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; execution Marks the most recently created dictionary entry as a word which is only available in execution mode. code here ( -- addr) The address of the next available dictionary location. constant dp ( -- addr) The address of the next available dictionary location pointer. Many be used to change the dictionary area. code immediate ( -- ) Used in the following form: : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; immediate Marks the most recently created dictionary entry as a word which will be executed when encountered during compilation rather than compiled. code interpret ( -- ) The forth top-loop; scan, locates, compiles and interprets symbols. The top-loop may be left with the word "bye". code literal ( n -- ) immediate compilation Typically used in the following form: 44 April 11, 1991 FORTH(3X) [ <_e_x_p_r_e_s_s_i_o_n> ] literal At execution time "n" will be left on the parameter stack. create pad ( -- addr) The lower address of a scratch area used to hold data form inter- mediate processing. The address or contents of "pad" may change and the data lost if the address of the next available dictionary loca- tion is changed. The minimum capacity of "pad" is minimum of 84 characters (bytes). code private ( -- ) Used in the following form: : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; private Marks the most recently created dictionary entry as a word which is only available in the dictionary it is created in. The word is not available when the dictionary is not the definitions vocabulary, "current". code quit ( -- ) Clears the parameter stack and performs the function of "inter- pret". Starts the forth interpreter and compiler. code recognizer ( -- ) Used in the following form: : <_n_a_m_e> ( str -- [str false] or [x true]) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; recognizer Marks the most recently created dictionary entry as a word which will perform the literal recognition function. Executed by "inter- pret" when an "entry" has not been found. The recognizer function for "forth" is "?number" and "?float" for "float". variable state ( -- addr) The address of a variable containing the compilation state. True indicated compilation is occurring, false that text interpretation is occurring. A Standard Program may not modify this variable and should instead use "[" and "]" to alter mode. create tib ( -- addr) The address of the text input buffer. This buffer is used to hold characters when the input stream is coming from the current input device. The minimum capacity of "tib" is 256 characters. code word ( char -- addr) Generates a null-terminated string by non-destructively accepting characters from the input stream until the delimiter character code or a control character is encounter or the input stream is exhausted. Leading delimiters and control characters are ignored. The entire character string is stored in memory beginning at "addr" as a sequence of bytes. Vocabulary The Forth-83 standard vocabulary management functions. The _t_i_l_e forth kernel extends the basic function set with primitive entry lookup and 45 FORTH(3X) April 11, 1991 literal recognition. Each vocabulary may have a literal recognition function which is automatically applied by "interpret" when the entry lookup fails. This allows easy extension of the input syntax for literal symbols. For examples see the "float" and the "rationals" vocabularies and files. code ' ( -- addr) Used in the form: ' <_n_a_m_e> ( -- addr) "addr" is the compilation address of <_n_a_m_e>. Gives an error message if <_n_a_m_e> is not found in the current active search order, "con- text". code ['] ( -- addr) immediate compilation Used in the form: ['] <_n_a_m_e> ( -- addr) Compiles the compilation address of <_n_a_m_e> as a literal. When the colon definition is later executed "addr" is left on the stack. If <_n_a_m_e> is not found an error message is given. set context ( -- addr) Variable containing the set of vocabularies in the search chain. The set is represented as a vector set in the _t_i_l_e forth kernel and may be manipulated with the functions from the "sets" extension. variable current ( -- addr) Variable containing a pointer to the current vocabulary for defini- tions. code definitions ( -- ) The compilation vocabulary, "current", is changed to be the same as the first vocabulary in the search order, "context". code find ( addr1 -- addr2 n) "addr1" is the address of a null-ended string. The string contains a word name to located in the currently active search order. If the word is not found, "addr2" is the string and "n" is false. If the word is found, "addr2" is the compilation address and "n" is set to one of two non- zero values. If the word found has the immediate attribute set, "n" is one. If the word is non-immediate, n is minus one (true). code forget ( -- ) Used in the form: forget <_n_a_m_e> ( -- ) If <_n_a_m_e> is found in the compilation vocabulary, delete <_n_a_m_e> from the dictionary and all words added to the dictionary after <_n_a_m_e> regardless of their vocabulary. Failure to find <_n_a_m_e> is an error condition. An error condition also exists if the compilation vocabulary is deleted. vocabulary forth ( -- ) The name of the primary vocabulary. Execution replaces the first vocabulary in the search order with "forth". "forth" is initially 46 April 11, 1991 FORTH(3X) the compilation vocabulary and the first vocabulary in the search order. New definitions become part of the "forth" vocabulary until a different compilation vocabulary is established. code forth-83 ( -- ) Assures that a Forth-83 Standard System is available. code last ( -- addr) Returns the compilation address of the latest defined entry in the current vocabulary. code lookup ( addr1 vocabulary -- addr2 n) "addr1" is the address of a null-ended string which is to be located in the "vocabulary" given as a parameter. If the word is not found, "addr2" is the string and "n" is false. If the word is found, "addr2" is the compilation address and "n" is set to one of two non-zero values. If the word found has the immediate attribute set, "n" is one. If the word is non-immediate, "n" is minus one. code only ( -- ) The compilation vocabulary, "current", is changed to be the same as the first vocabulary in the search order, "context". And all voca- bularies except the first is removed from the search list. code recognize ( addr1 -- [addr1 false] or [addr2 true]) "addr1" is the address of a null-ended string. The string is tested by each recognizer function in the currently active search order. If recognized the function will return the literal value in "addr2" and "true". In other cases the string is returned with "false". The recognizer functions for the "forth" and "float" vocabularies are "?number" and "?float". code restore ( entry -- ) Restores "current" to the parameter entry. Any words defined after "entry" are unlinked form the vocabulary. This is useful for real- izing lexical levels in forth. The lookup function cache is also flushed. An "nil" parameter will flush the whole cache. code seal ( -- ) The first (top) vocabulary is removed from the set of search voca- bularies, "context". This allows lexical levels using vocabularies. code words ( -- ) immediate Display the visible words in the current search chain, "context". Defining Words The Forth-83 standard defining functions. The _t_i_l_e forth kernel extends the Forth-83 Standard with additional functions for creating vocabulary entries, fields, and forward declaration. code : ( -- ) A defining word executed in the following form: : <_n_a_m_e> ( ... ) ... <_c_o_l_o_n-_d_e_f_i_n_i_t_i_o_n> ... ; 47 FORTH(3X) April 11, 1991 Create a word definition for <_n_a_m_e> in the compilation vocabulary and set compilation state. The text from the input stream is subse- quently compiled. <_n_a_m_e> is called a "colon definition". code ; ( -- ) immediate compilation Stops compilation of a colon definitions, sets interpret state. Additional actions may be taken for local variables and argument frames and an exception block. code code ( addr -- ) Used in the following form: <_a_d_d_r> code <_n_a_m_e> ( ... ) to create a kernel primitive which will execute code at the given address, "addr", when used. The "address" is assumed to be a pointer to a parameter-less procedure. code constant ( value -- ) A defining word executed in the following form: <_v_a_l_u_e> constant <_n_a_m_e> ( -- value) Create a dictionary entry form <_n_a_m_e> so that when <_n_a_m_e> is later executed, <_v_a_l_u_e> will be left on the stack. code create ( -- ) A defining word executed in the following form: create <_n_a_m_e> ( -- addr) Create a dictionary entry for <_n_a_m_e>. After <_n_a_m_e> is created, the next available dictionary location is the first byte of <_n_a_m_e>'_s parameter field. When <_n_a_m_e> is subsequently executed, the address of the first byte of <_n_a_m_e>'_s parameter field is left on the stack. "create" does not allocate space in <_n_a_m_e>'_s parameter field. The dictionary location is always aligned before the entry is created. code entry ( parameter mode code name -- ) Creates a new entry in the current definitions vocabulary with the given arguments. The entry becomes the "last" entry in the vocabu- lary. code field ( offset -- ) Used in the following form: <_o_f_f_s_e_t> field <_n_a_m_e> ( addr1 -- addr2) When later <_n_a_m_e> is used it will add the <_o_f_f_s_e_t> to the top of the parameter stack. code forward ( -- ) Used in the following form to define a symbol which will be defined later: forward <_n_a_m_e> ( ... ) If the symbol is executed it will indirectly execute "abort". When the symbol is later defined the forwarded symbol is automatically redirected to the newly created symbol. code variable ( -- ) A defining word executed in the following form: variable <_n_a_m_e> ( -- addr) 48 April 11, 1991 FORTH(3X) A dictionary entry for <_n_a_m_e> is created and four bytes are allo- cated in its parameter field. This parameter field is to be used for contents of the variable. The application is responsible for initializing the contents of the variable which is created. When <_n_a_m_e> is later executed, the address of its parameter field is placed on the stack. code vocabulary ( -- ) A defining word executed in the following form : vocabulary <_n_a_m_e> ( -- ) A dictionary entry for <_n_a_m_e> is created which specifies a new ordered list of word definitions. Subsequent execution of <_n_a_m_e> replaces the first vocabulary in the search order with <_n_a_m_e>. When <_n_a_m_e> becomes the compilation vocabulary new definitions will be appended to <_n_a_m_e>'_s list. INTERNALS For the internal data structures of the _t_i_l_e forth kernel see the source files "internals.f83" and the manual file "internals". The C definition of the data structures may be found in the file "kernel.h". SEE ALSO _t_i_l_e(_1), _m_e_m_o_r_y(_3_X), _c_o_m_p_i_l_e_r(_3_X), _l_o_c_a_l_s(_3_X), _e_x_c_e_p_t_i_o_n_s(_3_X), _f_l_o_a_t(_3_X), _s_t_r_i_n_g(_3_X), _q_u_e_u_e_s(_3_X), _m_u_l_t_i-_t_a_s_k_i_n_g(_3_X). NOTE The function lists are sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University 49 FORTH(3X) April 11, 1991 S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 50 August 1, 1990 INTERNALS(3X) NAME internals - tile forth kernel internal data structures SYNOPSIS #include internals.f83 forth DESCRIPTION High level definitions of the internal data structures of the _t_i_l_e forth kernel. Defines the structure of vocabulary entries; the linkage struc- ture, name string, mode field, interpretation code, and parameter field. Utility functions for displaying the current vocabulary search order, the current definitions vocabulary and the internal state of an entry. General definitions iterator for extraction of entries of specific code type. Numerical constants Predefined constants for some of the most common values used for storage allocation and integer value initialization. constant BITS/BYTE ( -- num) Number of bits per byte. constant BITS/WORD ( -- num) Number of bits per word in stack data etc. constant BYTES/WORD ( -- num) Number of bytes per word. constant MAX_INT ( -- int) Maximum integer number in two's complement. constant MIN_INT ( -- int) Minimum integer number in two's complement. Entry structure The internal fields of an entry in a _t_i_l_e forth vocabulary. Defined as a structure with the traditional fields; link, name, mode, code, and parameter. Definition of the entry mode and interpretation code field. struct.type ENTRY ( -- ) Structure of vocabulary entries. Contains the fields; "+link", "+name", "+mode", "+code", and "+parameter". ptr +link ( entry -- addr) Field access of link to predecessor entry in vocabulary list. The vocabulary chain is maintained as a linked list in definition order and may be manipulated with the "lists" extensions. ptr +name ( entry -- addr) 51 INTERNALS(3X) August 1, 1990 Field access of name string of an entry. The string is stored as a null terminated character sequence and may be manipulated using the "string" extensions. long +mode ( entry -- addr) Field access of mode bit field of an entry. See also "ENTRY-MODES" for the definition of the bit fields. long +code ( entry -- addr) Field access of code enumerative of an entry. Stored as a number, enum, or pointer to high level code. See also "ENTRY-CODES". If the code field contains a number larger than the exception entry code "EXCEPTION" it is interpreted as a pointer to a high level management block by the inner address interpreter. long +parameter ( entry -- addr) Field access of parameter part of entry structure. Stored as a long. May contain a pointer to the body of the entry. This is the case for colon definitions and other entries with bodies larger than a "cell". The kernel word ">body" returns the contents of this field. bitfield.type ENTRY-MODES ( -- ) Bit field structure definition of the possible set of entry modes. The kernel uses four bits and allows applications to use the bits within the three most significant bytes (bit 8-31). Defines the modes "IMMEDIATE", "EXECUTION", "COMPILATION", and "PRIVATE" as bit fields. These may be manipulated with the "bitfields" extension. bit IMMEDIATE ( -- pos width) Access of immediate bit field in the mode field of an entry. If the bit is set the entry is an "immediate" word. This bit is set by the kernel word "immediate". bit EXECUTION ( -- pos width) Access of execution bit field in mode. If the bit is set the entry is not visible in compilation mode. This bit may be set by the ker- nel word "execution". bit COMPILATION ( -- pos width) Access of compilation bit field in mode. If the bit is set the entry is not visible in execution mode. This bit may be set by the kernel word "compilation" bit PRIVATE ( -- pos width) Access of private bit field in mode. If the bit is set the entry is only visible when the vocabulary in which it is defined is currently the definitions, "current", vocabulary. bits RESERVED ( -- pos width) Access of reserved bit field in mode. These bits of the mode are reserved for the kernel. Bits 8-31 may be freely used by applica- tions. 52 August 1, 1990 INTERNALS(3X) enum.type ENTRY-CODES ( -- ) Predefined code types. Used by the kernel, inner interpreter, to determine management of primitives. Defines the enumerates; "CODE", "COLON", "VARIABLE", "CONSTANT", "VOCABULARY", "CREATE", "USER", "LOCAL", and "EXCEPTION". Codes larger than "EXCEPTION" are regarded as pointers to forth level management code, and are used to implement high level management compiled by the words following "does>". enum CODE ( -- enum) Numeral for machine level code management. The parameter field of the entry is a pointer to a C procedure implementing the function. The inner interpreter will call the procedure. enum COLON ( -- enum) Numeral for forth level code management. The parameter field of the entry is a pointer to the body of the definition. The inner inter- preter will push the instruction pointer onto the return stack and use the parameter field as the new instruction pointer. enum VARIABLE ( -- enum) Numeral to mark variable management of entry. The parameter field of the entry is used for the variable area. The address of the parameter field is pushed onto the data stack. enum CONSTANT ( -- enum) Numeral to mark constant management of entry. The parameter field contains the constant value. The value is pushed onto the data stack. enum VOCABULARY ( -- enum) Numeral to mark vocabulary management of entry. The parameter field contains a pointer to the latest defined entry in the vocabulary. The vocabulary is appended first to the vocabulary search set, "context". enum CREATE ( -- enum) Numeral to mark create, symbol, management of entry. The parameter field contains a pointer to the data area for the entry. This pointer is pushed onto the parameter stack by the inner inter- preter. enum USER ( -- enum) Numeral to mark user management of entry. The parameter field con- tains the offset from the task instance pointer. The address of the user variable, calculated from the current running task pointer, "running", and the offset is pushed onto the parameter stack by the inner interpreter. enum LOCAL ( -- enum) Numeral to mark local variable management of entry. The parameter field contains the offset within the current frame to the location of the argument or local variable. The value of the frame variable is pushed onto the parameter stack. 53 INTERNALS(3X) August 1, 1990 enum FORWARD ( -- enum) Numeral to mark forward management of entry. The parameter field contains initially "nil" and is replaced if the entry is redefined later. If the entry is used before defined an error message is given and execution is aborted. enum FIELD ( -- enum) Numeral to mark field management of entry. The parameter field con- tains the field offset. The offset is added to the pointer on top of the parameter stack. enum EXCEPTION ( -- enum) Numeral to mark exception variable management of entry. The parame- ter field contains a pointer to the entry. Utility functions Functions for displaying the current vocabulary search path and internal state of entries. Also display function to retrieve the current set of vocabularies. : .entry ( entry -- ) Given a pointer to an entry prints all fields of the entry. : .context ( -- ) Similar to "words" but prints the current state of the vocabulary search set, "context". : .current ( -- ) Prints the name of the current definitions vocabulary. : .entries ( code -- ) Prints the name of the available entries of the given code type along the current definitions vocabulary, "current". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_i_n_g(_3_X), _e_n_u_m_e_r_a_t_e_s(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_i_t_f_i_e_l_d_s(_3_X), _b_l_o_c_k_s(_3_X), _l_i_s_t_s(_3_X), _s_e_t_s(_3_X). EXAMPLES To print the internal fields of the entry _f_o_r_t_h, and access and verify its code type: #include internals.f83 A procedure to print out all variables in the "current" vocabulary: #include blocks.f83 #include lists.f83 blocks lists : .variables ( -- ) last 54 August 1, 1990 INTERNALS(3X) block[ ( entry -- ) dup +code @ VARIABLE = if .name space else drop then ]; map-list ; NOTE The function list in each sub-section is sorted in logical order. The type and mode of the entries are indicated together with their parameter stack effect. WARNING These extensions are very implementation dependent and caution must be take as code written using these definitions is not directly portable to other forth environments. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 55 IO(3X) April 11, 1991 NAME io - tile kernel unix standard io interface SYNOPSIS io DESCRIPTION The _t_i_l_e forth kernel support word set for the standard unix system calls and library for io. vocabulary io ( -- ) The Unix standard library io functions. The io vocabulary is an non-standard extension of Forth-83 and not directly portable to other forth environments. code open ( filename flags mode -- des) Opens a named file for reading and/or writing, as specified by the flags argument. The parameter is used when a new file is created to define the access mode of the file. Return a file descriptor or error. code close ( des -- int) Closes the file associated with the descriptor. Returns the value 0 is successful else the value -1 is returned to indicate an error. code read ( des buf nbytes -- int) Attempts to read nbytes of data from the file references by the descriptor into the buffer pointed to by buf. Returns the number of bytes actually read. If EOF the return is 0. code write ( des buf nbytes -- int) Attempts to write nbytes of data from the buffer pointer to by buf to the file referenced by the descriptor. Returns the number of bytes actually written otherwise the return value -1 to indicate an error. code lseek ( des offset whence -- int) Positions the file referenced by the descriptor to the position given by the offset and the position mode whence. The modes are absolute (0), relative (1), and relative end of file (2). Returns the new position on the file in bytes else the value -1 to indicate an error. code fdopen ( des type -- stream) Associates a stream with the file descriptor des. code fopen ( filename type -- stream) Opens the file named by filename and associates a stream with it. If the open is successful the word return a pointer to the the stream else NIL is returned. The type parameter is a string with one of the following values: "r" for read, "w" for write, "a" for append, "r+" for update, "w+" for truncate or create for update, and "a+" open or create for update for EOF. 56 April 11, 1991 IO(3X) code fclose ( stream -- int) Writes out any buffered data and closes the stream. Internal buffers are freed. Returns 0 if successful else the value EOF is returned. code fgetc ( stream -- int) Reads a character for the stream. Returns EOF at EOF or at an error. code fgets ( stream buf nbytes -- buf) Reads a sequence of characters from the stream into the buffer buf until EOF or NEWLINE or nbytes-1 have been received. The input string is null terminated. code fputc ( stream char -- int) Writes a character to the stream. Returns the character written. code fputs ( stream buf -- int) Writes the null terminated string to the stream. Returns EOF on error. code ungetc ( stream char -- int) Puts back a character on the stream. code ftell ( stream -- int) Return current position on stream. fseek ( stream position -- int) Move stream pointer to a new position. fflush ( stream -- int) Flush buffered data on the stream. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). NOTE The function list is sorted in logical order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1991 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 57 IO(3X) April 11, 1991 Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 58 August 6, 1990 LISTS(3X) NAME lists - single linked lists definitions SYNOPSIS #include lists.f83 lists DESCRIPTION This library supports definition and manipulation of single linked lists. The list is assumed to have a pointer field first in each ele- ment. The pointer gives access to the next element in the list. The list is terminated by "nil". The _t_i_l_e forth kernel vocabulary chain is realized as a single linked lists of entries. : ?empty-list ( list -- bool) Returns "true" if the list is empty else "false". : ?map-list ( list block[element -- bool] -- ) List conditional iterator function. The code block is called for each element of the list while the block returns "false". : ?member-list ( element list -- bool) Returns "true" if the element is a member of the list else "false". : append-list ( element list -- ) Appends the element last in the list. The list is searched first so that the element is not a member of the list. In this case no operation is performed. : apply-list ( offset list -- ) List iteration function accessing each element of the list at the given offset as a pointer field and executing the field as an entry. : empty-list ( list -- ) Assigns a list to become the empty list. The list will point to "nil". : insert-list ( element list -- ) Inserts the element into the list. If the list a list element the parameter element is inserted after. : list ( -- ) Used in the following form: list <_l_i_s_t-_n_a_m_e> ( -- addr) to create a list header. The header is initiated to "nil". : map-list ( list block[element -- ] -- ) List iterator function. The code block is called for each element of the list. vocabulary lists ( -- ) 59 LISTS(3X) August 6, 1990 The single linked list extension vocabulary. Include into the voca- bulary search set, "context", to allow access to these functions. : size-list ( list -- num) Returns the size of the list, i.e., the number of element in the list. INTERNALS The _l_i_s_t_s vocabulary contains the following private definition to search lists of append and check membership. : search-list ( element list -- [element last] or [false]) private Searches through the list after the element. If not found returns the searched and the last element so that the element may be inserted. If found returns "false". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _b_l_o_c_k_s(_3_X). EXAMPLES The internal definition of a vocabulary entry in the _t_i_l_e forth kernel has the following structure. The entry list may be manipulated with the "lists" extensions. #include structures.f83 #include lists.f83 #include blocks.f83 structures lists blocks struct.type ENTRY ( -- ) ptr +link ( entry -- addr) ptr +name ( entry -- addr) long +mode ( entry -- addr) long +code ( entry -- addr) long +parameter ( entry -- addr) struct.end last block[ ( entry -- ) . ]; map-list NOTE The function list is sorted in ASCII order. The type and mode of the entry is indicated together with the parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in 60 August 6, 1990 LISTS(3X) the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 61 LOCALS(3X) August 1, 1990 NAME locals - tile kernel argument binding and local variable functions SYNOPSIS locals DESCRIPTION The _t_i_l_e kernel support for argument binding and local variables in colon definitions. The _t_i_l_e forth virtual machine model support building and disposing of argument frames. The frame is build directly on the parameter stack. This minimizes the amount of data that has to be moved. Arguments and local variables are accessed by a frame pointer. The frame pointer is automatically maintained by the virtual machine. On the exit of a colon definition using "locals" the frame is disposed and return values moved to their correct position on the parameter stack. Other forth implementation build the frame on a separate stack or on the return stack. This implementation is much more efficient when the number of return values is often less than the number of arguments and local variables. code -> ( x -- ) compilation Assigns an argument or local variable with the value "x". Used in the following form: <_v_a_l_u_e> -> <_f_r_a_m_e-_v_a_r_i_a_b_l_e> The word after the assignment operator must be a <_f_r_a_m_e-_v_a_r_i_a_b_l_e> otherwise an error is accounted. The compiler does not check this error situation. code exit ( -- ) compilation Performs the equivalent action of the normal "exit" but also restores the stack after argument binding and local variables. vocabulary locals ( -- ) Vocabulary containing the argument binding and local variable extension. Include into the vocabulary search structure, "context", to allow access to these extensions. code { ( -- ) immediate compilation Starts the named argument and local variable compiler. Used in the following forms: { <_a_r_g_u_m_e_n_t-_n_a_m_e_s> | <_l_o_c_a_l-_n_a_m_e_s> -- <_a_n_y> } or { <_a_r_g_u_m_e_n_t-_n_a_m_e_s> -- <_a_n_y> } or { | <_l_o_c_a_l-_n_a_m_e_s> -- <_a_n_y> } The different parts are as shown optional. The only restriction is that the definition of argument and local variable names is ter- minated by "}" or "--". In the "--" case characters until "}" are skipped and may be regarded as a comment. Return values are not named. 62 August 1, 1990 LOCALS(3X) INTERNALS The following set of functions are mainly used to implement the argument binding and local variable frame management. code (link) ( arguments -- frame old-frame-pointer) compilation Compiled by "{" to perform the run-time action of building the argument and local variable frame. The frame is built directly on the parameter stack to minimize data movement. The frame consists of the arguments and stack area for the local variables. The old frame pointer is stored on the top of the parameter stack, making lexical levels possible. A pointer to the top of the frame, i.e., the parameter stack top, is saved on the return stack so that return values may be moved down to their correct position on the parameter stack and the old frame pointer restored. The frame pointer will point to the first element below the first argument. This element will become the top of stack if no values are returned. code (local) ( -- addr) compilation Returns the address of an argument or local variable within the current frame using an inline literal offset. To access the address of the first variable in the frame the offset should be one. code (local!) ( value -- ) compilation Stores "value" to an argument or local variable within the current argument frame using an inline literal offset. To assign the first variable in the frame the offset should be one. code (local@) ( -- value) compilation Access the value of an argument or local variable within the current argument frame using an inline literal offset. To access the value of the first variable in the frame the offset should be one. code (unlink) ( frame return -- return) compilation Drops the frame and move the return values down. The old frame pointer is restored. code (unlink;) ( frame return -- return) compilation Drops the frame and move the return values down. The old frame pointer is restored. Leaves the colon definition. Compiled by the word ";". code (unlink>) ( frame return -- return) compilation Drops the frame and move the return values down. The old frame pointer is restored. Assigns the "code" type of the latest defini- tion and leaves the colon definition. Compiled by the word "does>". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). 63 LOCALS(3X) August 1, 1990 NOTE The function list is sorted in ASCII order. The type and mode of the entry is indicated together with the parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 64 August 6, 1990 MACROS(3X) NAME macros - macro expansion of colon definitions SYNOPSIS #include macros.f83 macros DESCRIPTION Allows definition of macro colon definitions to reduce the overhead of procedure calls at run-time to the price of memory. The macro package may be used, after profiling of an application, to mark the most criti- cal low level definitions and hereby increase performance. Macro defini- tion may also be used to create alias names for definitions. : .macro ( -- ) Used in the following form: .macro <_m_a_c_r_o-_n_a_m_e> to display the internal information about the macro definition. The information is displayed in the following form: macro# <_m_a_c_r_o-_a_d_d_r_e_s_s> size: <_m_a_c_r_o-_s_i_z_e> body: <_m_a_c_r_o-_b_o_d_y- _a_d_d_r_e_s_s> Use mainly for debugging and code verification purpose. : macro ( -- ) Used in the following form to mark the latest colon definition as a macro: : <_m_a_c_r_o-_n_a_m_e> ( ... ) ... <_m_a_c_r_o-_d_e_f_i_n_i_t_i_o_n> ... ; macro Used in the same way as "immediate" and other mode classifiers. The code section is not restricted to sequential code. Control structures, condition and iteration statements, are allowed as all branches are relative. Special care should be taken if the macro definition contains "exit", "tail-recurse" or "recurse" as the result is unpredictable when expanded. vocabulary macros ( -- ) Vocabulary containing the macro extension definitions. Include into the vocabulary search chain, "context", to gain access to this library. INTERNALS Private definitions in the _m_a_c_r_o_s vocabulary; ptr +body ( macro -- addr) private Returns address of field in "MACRO" structure to pointer to code section of the macro. long +size ( macro -- addr) private Returns address of field in "MACRO" structure to byte size of macro code. struct.type MACRO ( body size -- ) private Structure definition used by "macro" to keep information about a 65 MACROS(3X) August 6, 1990 macro code definition. Internal fields are "+body" and "+size". An instance of this structure will perform the run-time action for a macro definitions. If compilation state the macro body is expanded into the current definition otherwise the macro body is executed. All macro definitions are "immediate". The "MACRO" structure type contains the fields "+body" and "+size". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _i_n_t_e_r_n_a_l_s(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X). EXAMPLES An example showing how to create macros for some additional relational operators: #include macros.f83 macros : <> ( x y -- bool) = not ; macro : >= ( x y -- bool) < not ; macro : <= ( x y -- bool) > not ; macro The "macro" function may also be used to the allow simple aliasing and renaming at very low execution cost. NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. WARNING A "macro" definition containing "exit" will work correctly in execution mode but expanded in a colon definition the "macro" will cause the definition to be exited. This is in most case not the wanted behavior. Special care should be taken for "macro" definitions which contain "exit", "recurse", and "tail-recurse". Also argument and local vari- ables, and exception blocks should not be part of a macro colon defini- tion. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, 66 August 6, 1990 MACROS(3X) except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 67 MAPPINGS(3X) August 7, 1990 NAME mappings - vector represented mappings definitions SYNOPSIS #include mappings.f83 mappings DESCRIPTION Library for mappings represented as vectors. The mapping consists of pairs of cells, domain and range, and is terminated by a double zero pair. This mapping representation is mainly used for small mapping sets as all operations are dependent on the size of the mapping. The pair zero-zero cannot be a member of the mapping. : .mapping ( mapping -- ) Assuming that the domain is entry addresses this word will display the mapping as a set of pairs. The following form is used: { <_p_a_i_r_s> } where the <_p_a_i_r_s> _a_r_e _i_s _t_h_e _f_o_r_m_a_t: ( <_e_n_t_r_y> <_v_a_l_u_e> ) : ?empty-mapping ( mapping -- bool) Returns "true" if the mapping is empty else "false". : ?map-mapping ( mapping block[range domain -- bool] -- ) Conditional iterator function for mappings. The block will receive the pair, domain and range, as parameters and should return a boolean flag indicating is the iterator should terminate. The return value "true" will terminate the iterator. : ?range-mapping ( domain mapping -- bool) Returns "true" is the domain is defined and has a range in the map- ping else "false" is returned. : add-mapping ( range domain mapping -- ) Adds the domain-range pair to the mapping. If the domain is already defined in the mapping the new range value is stored. : empty-mapping ( mapping -- ) This word will empty the mapping by assigning the terminal pair first in the mapping vector. : map-mapping ( mapping block[range domain -- ] -- ) Iterator function for mappings. The block will receive the domain- range pair as parameters. The block is called for all pairs in the mapping. : mapping ( size -- ) Used in the following form: <_s_i_z_e> mapping <_n_a_m_e> ( -- mapping) to create a mapping variable. All operation are destructive on map- ping variables. The maximum number of domain-range pairs in a 68 August 7, 1990 MAPPINGS(3X) mapping set is <_s_i_z_e> - 1. vocabulary mappings ( -- ) The vector represented mapping library vocabulary. Include into the vocabulary search set, "context", to allow access to these exten- sions. : range-mapping ( domain mapping -- addr) Returns the range address, "addr", for the domain in the mapping. The value "nil" is returned if the domain is not a member of the mapping. The address may be used to manipulate the range value. Most mapping operations are destructive. This makes the address only valid until the next destructive mapping operation. : remove-mapping ( domain mapping -- ) Removes the domain-range pair from the mapping. : size-mapping ( mapping -- num) Returns the number of domain-range pairs in the mapping. INTERNALS The _m_a_p_p_i_n_g_s library contains the following internal function to search a mapping and access the domain-range pair. field +domain ( mapping -- addr) private Access field for domain address of a domain-range pair in a mapping vector. field +pair ( mapping -- addr) private Access field for the next pair address in a mapping vector. field +range ( mapping -- addr) private Access field for range address of a domain-range pair in a mapping vector. : search-mapping ( domain mapping -- [addr1] or [domain addr2 false]) Primitive mapping search function. Tries to locate the domain-range pair in the mapping. If found the pair address, "addr1", is returned and may be accessed with the fields; "+domain", and "+range". If not found the domain and the address of the terminal pair together with the flag "false" is returned. The function is used to implement the words "add-mapping", "remove-mapping", "?range-mapping", and "range-mapping". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _b_l_o_c_k_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entry is indicated together with the parameter stack effect. 69 MAPPINGS(3X) August 7, 1990 COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 70 August 1, 1990 MEMORY(3X) NAME memory - tile kernel dynamic memory allocation functions SYNOPSIS memory DESCRIPTION The _t_i_l_e forth kernel support word set for dynamic memory allocation and reclaim from the run-time heap. Used by the kernel to allocate memory for tasks, entries, strings, etc. code free ( addr -- ) Returns an allocated block of memory back to the run-time heap. code malloc ( bytes -- addr) Allocates a block of size "bytes" and returns a pointer to the memory area. Returns "nil" if the heap is saturated. vocabulary memory ( -- ) Vocabulary containing the heap management extension. Include into the vocabulary search set, "context", to allow access of this library. code realloc ( bytes addr1 -- addr2) Resizes an allocated block on the heap. If the new size is larger than the grow size of the block a new block is allocated and the old blocks contains is copied and released back to the memory pool. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the 71 MEMORY(3X) August 1, 1990 original English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 72 August 1, 1990 MULTI-TASKING(3X) NAME multi-tasking - tile forth kernel extensions for concurrent programming SYNOPSIS #include multi-tasking.f83 multi-tasking DESCRIPTION The _t_i_l_e kernel and forth level extensions to allow concurrent program- ming with tasks, condition variables, semaphores, channels and rendez- vous. The tasking switch mechanism in the _t_i_l_e kernel is not time- multiplexed and applications are required to periodically call the task switch function, "detach", or, "resume", or synchronization functions such as semaphores, condition variables, etc. This extension implement the major concurrent programming concepts and allows programming for a common memory or distributed model. : .task ( task -- ) Displays the internal state of a task. The state is not the state of the running task as this word will display the memory structure of a task, and not the virtual machine state. A task cannot display its own state. constant >terminate ( -- addr) Constant containing a pointer to the terminate function. Used by "task" to automatically terminate task which arrive at the end of their task body, i.e., forth-level code section. : ?avail ( chan -- bool) Check whether a channel "receive" operation will not block. Data is available directly. Returns "true" if data is directly available without waiting else "false". : ?awaiting ( -- bool) immediate Used in the following form: ?awaiting <_r_e_n_d_e_z_v_o_u_s-_n_a_m_e> ( -- bool) in a server task to check if a client task is waiting for service. Returns "true" if a client task is waiting else "false". : ?wait ( semaphore -- bool) Checks the semaphore counter to determine if a "wait" operation will make a task wait. Returns "true" in this case otherwise "false". enum.type COMMUNICATION-MODELS ( -- ) Enumerate type used to select the operation type of a channel. The models are; "ONE-TO-ONE", "ONE-TO-MANY", and "MANY-TO-ONE". struct.type CHAN ( model -- ) Used in the following form to create a channel: <_c_o_m_m_u_n_i_c_a_t_i_o_n-_m_o_d_e_l> CHAN <_c_h_a_n-_n_a_m_e> ( -- chan) The channel is represented by two synchronization semaphores and a 73 MULTI-TASKING(3X) August 1, 1990 common data area. May be used for three major communication styles between tasks. These are defined by the enumeration type "COMMUNICATION-MODES". The operations on a channel are "send", "receive" and "?avail". struct.type CONDITION ( -- ) Used as in the following form: CONDITION <_c_o_n_d_i_t_i_o_n-_n_a_m_e> ( -- condition) to create and initiate a named condition queue variable. The possi- ble operations, other than queue operations, on a condition queue are "await" and "cause". enum DELAYED ( -- enum) Task status code for task performing "delay". Will resume "RUNNING" after the "delay" operation. enum IOWAITING ( -- enum) Task status code for task waiting for IO. The foreground task is currently the only task allowed to perform io-operations, input, as these are not reentrant. enum MANY-TO-ONE ( -- enum) Selects the many-to-one communication mode of a channel. Several sending tasks are allowed to communicate with a service task. enum ONE-TO-ONE ( -- enum) The channel is to be operated in a one-to-one manner. enum ONE-TO-MANY ( -- enum) The channel is to be operated in a one-to-many manner. Several receiving tasks are possible on the channel. Data sent on the chan- nel is maintained from corruption. enum READY ( -- enum) Task status code for newly created tasks, ready for scheduling. struct.type RENDEZVOUS ( -- ) Used in the following form: RENDEZVOUS <_r_e_n_d_e_z_v_o_u_s-_n_a_m_e> ( arg -- res) to create a rendezvous name. This name may then be used as a func- tion service by some task with "accept". <_r_e_n_d_e_z_v_o_u_s-_n_a_m_e> ( arg -- res) The function always takes one argument and always returns one result value. The service block is terminated by the word "accept.end". enum RUNNING ( -- enum) Task status code for running, scheduled, tasks. struct.type SEMAPHORE ( value -- ) Used in the following form: <_v_a_l_u_e> SEMAPHORE <_s_e_m_a_p_h_o_r_e-_n_a_m_e> ( -- semaphore) to create and initiate a named semaphore. The possible operations on a semaphore are "?wait", "wait", and "signal". 74 August 1, 1990 MULTI-TASKING(3X) struct.type TASK-HEADER ( -- ) Definition of the instance structure of a task header. Defines the field names for a task; "+queue", "+sp", "+s0", "+rp", "+r0", "+fp", and "+ep". enum.type TASK-STATUS-CODES ( -- ) Enumerate defining the possible task status codes. The codes are; "READY", "DELAYED", "RUNNING", "WAITING", "IOWAITING", and "TER- MINATED". enum TERMINATED ( -- enum) Task status code for terminated tasks. enum WAITING ( -- enum) Task status code for task performing a generic wait operation. : accept ( -- arg) immediate Using in the following form: accept <_r_e_n_d_e_z_v_o_u_s-_n_a_m_e> ( arg -- res) ... <_s_e_r_v_i_c_e-_d_e_f_i_n_i_t_i_o_n> ... accept.end to accept calls on the rendezvous. When a client task calls the rendezvous the argument from client is passed to the server task that performed the accept. : accept.end ( res -- ) immediate Marks the end of an accept block in a server task. The result is passed to the client task and both may continue in parallel. : activate ( task -- ) Inserts a task first in the queue of runnable task and resumed. The task is assumed to have be scheduled and deactivated. The task is now marked as "RUNNING". : await ( condition -- ) Causes the running task to wait for a condition. The task is deac- tivated and places in the queue associated with the condition. The task status is "WAITING" while in the queue. task.field byte ( -- ) Used in the following form: byte <_u_s_e_r-_n_a_m_e> ( -- addr) within a task type definitions. Creates a user variable access name to a byte. : bytes ( size -- ) Used in the following form to create named local structures and data within task instances: <_n_u_m_b_e_r> bytes <_u_s_e_r-_f_i_e_l_d-_n_a_m_e> ( -- addr) Should only be used within the layout section of a task type. : cause ( condition -- ) Activates the first waiting task in the condition queue. The task status will become "RUNNING". 75 MULTI-TASKING(3X) August 1, 1990 : deactivate ( queue task -- ) Removes a task from the queue of runnable task and inserts it into the given queue. The task is marked as "WAITING". The next runn- able task is resumed. : delay ( n -- ) Delays a task a number of task switches. The delay is not real-time but relative time. The task status is "DELAYED" during the delay. code detach ( -- ) Deactivate the current running task and resumes the next task in the queue over runnable tasks. task.field enum ( -- ) Used in the following form: enum <_u_s_e_r-_n_a_m_e> ( -- addr) within a task type definitions. Creates a user variable access name to an enumerative, four bytes counter. variable foreground ( -- addr) Variable containing a pointer to the foreground task. code fork ( -- task) Copies the current task and returns a pointer to it. The child task will receive a pointer to the parent task as result of fork. The parent will receive a pointer to the child task. The child is scheduled directly. : join ( task -- ) Delay a task until the task given as parameter terminates. The task status is "WAITING" during the join delay. task.field long ( -- ) Used in the following form: long <_u_s_e_r-_n_a_m_e> ( -- addr) within a task type definitions. Creates a user variable access name to a long, four bytes. task.field ptr ( -- ) Used in the following form: ptr <_u_s_e_r-_n_a_m_e> ( -- addr) within a task type definitions. Creates a user variable access name to a pointer, four bytes. vocabulary multi-tasking ( -- ) Vocabulary containing the multi-tasking extensions to the Forth-83 Standard. These extensions are realized both as primitives and on the forth level. : mutex ( -- ) Used in the following form: mutex <_s_e_m_a_p_h_o_r_e-_n_a_m_e> ( -- semaphore) to create a semaphore for mutual exclusion. Should not be used within other structures as this definition is not a structure 76 August 1, 1990 MULTI-TASKING(3X) definition but a code definition. : new-task ( -- task) Used in the following form: new-task <_t_a_s_k-_t_y_p_e-_n_a_m_e> ( -- task) to create a new task instance of a task type. Allocates and schedules the task instance. : receive ( chan -- data) Receives data from channel. Will wait until sender has performed "send". : resume ( task -- ) Activates the given task. The task must be a member of the runnable tasks, i.e., scheduled and waiting for activation. variable running ( -- addr) Variable containing a pointer to the current running task. code schedule ( task -- ) Schedules the given task and activates it immediately. : send ( data chan -- ) Sends data on a channel. Sender will wait until receiver has per- formed "receive". : signal ( semaphore -- ) If there is a waiting task on the semaphore this task is resumed else the semaphore counter is incremented. : struct ( -- ) Creates a named user variable of a structure size. Use in the fol- lowing form: struct <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> <_u_s_e_r-_n_a_m_e> ( -- addr) code task ( users parameters returns code -- task) Used to create a task instance. The "users" parameter defines the size of the task local variable area in bytes. The "parameters" and "returns" arguments define the size of the tasks parameter and return stack in "cells". Last the "code" parameter is a pointer to forth-level code. Returns a pointer to a task. The task is allo- cated from the run-time heap and not the dictionary. The "memory" extension word "free" should be used to reclaim the allocated area if needed. : task.body ( -- ) Used within a task type definition structure to indicate the begin- ning of the task body part and the end of the user variables. : task.end ( -- ) Ends a task type definition. struct.type task.type ( parameters returns -- ) Used in the following form to start the definition of a task type: 77 MULTI-TASKING(3X) August 1, 1990 <_p_a_r_a_m_e_t_e_r_s> <_r_e_t_u_r_n_s> task.type <_t_a_s_k-_t_y_p_e-_n_a_m_e> { <_u_s_e_r-_v_a_r_i_a_b_l_e_s> } task.body <_t_a_s_k-_b_o_d_y-_d_e_f_i_n_i_t_i_o_n> task.end The two parameters, parameters and returns, define the size in cells of these two areas within a task instance. Local user area is defined by the task field names; "byte", "bytes", "word", "long", "enum", "ptr", and "struct". code terminate ( -- ) Terminates the current running task and resumes the next task in the runnable task queue. code user ( offset -- ) Used in the following form to create a local, user, variable within the task instance: <_o_f_f_s_e_t> user <_u_s_e_r-_n_a_m_e> ( -- addr) The offset is a relative address from the task pointer. : wait ( semaphore -- ) Dequeues the task and places it into the semaphore waiting queue if the semaphore counter is zero otherwise the counter is decrements and the task continues. The task status is "WAITING" during the semaphore wait delay. : who ( -- ) Displays the current queue of runnable tasks. task.field word ( -- ) Used in the following form: word <_u_s_e_r-_n_a_m_e> ( -- addr) within a task type definitions. Creates a user variable access name to a word, two bytes. INTERNALS Private definitions in the _m_u_l_t_i-_t_a_s_k_i_n_g vocabulary; struct CHAN +arg ( rendezvous -- addr) private Structure field within a rendezvous which is the channel for argu- ment passing to the server task. ptr +body ( task.type -- addr) private Field access to task type pointer to task body code. long +count ( semaphore -- addr) private Field access to semaphore value. long +data ( chan -- addr) private Field access to the common data area. Used as holding place for data sent until received. ptr +ep ( task -- addr) private Field access of task exception frame pointer. 78 August 1, 1990 MULTI-TASKING(3X) ptr +fp ( task -- addr) private Field access of task argument frame pointer. ptr +ip ( task -- addr) private Field access of task instruction pointer. struct CONDITION +not.zero ( semaphore -- addr) private Field access to semaphore condition for tasks waiting for not zero count. long +parameters ( task.type -- addr) private Field access of number of cells for parameter stack of task type. struct QUEUE +queue ( task -- addr) private Field access of system queue of task instances. ptr +r0 ( task -- addr) private Field access of task return stack bottom pointer. struct SEMAPHORE +received ( chan -- addr) private Field access to the received synchronization semaphore. struct CHAN +res ( rendezvous -- addr) private Structure field within a rendezvous which is the channel for result passing from the server task to the client task. long +returns ( task.type -- addr) private Field access of number of cells for return stack of task type. ptr +rp ( task -- addr) private Field access of task return stack pointer. ptr +s0 ( task -- addr) private Field access of task bottom of parameter stack pointer. struct SEMAPHORE +sent ( chan -- addr) private Field access to the sent synchronization semaphore. ptr +sp ( task -- addr) private Field access of task parameter stack pointer. enum +status ( task -- addr) private Field access of task status. See "TASK-STATUS-CODES" for possible codes. long +users ( task.type -- addr) private Field access of number of bytes for user area of task type. struct CONDITION +waiting ( condition -- queue) private Field access to condition queue of waiting tasks. : make-task ( task.type -- task) private Creates an anonymous task given a task type instance. Used in the following form: 79 MULTI-TASKING(3X) August 1, 1990 as <_t_a_s_k-_t_y_p_e-_n_a_m_e> make-task ( -- task) : task.field ( size -- ) private Fix size field meta-word. Used to create primary set of field type names, "byte", "word", "long", "ptr", and "enum". Should only be used for definitions internal to "multi-tasking". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _e_n_u_m_e_r_a_t_e_s(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X), _q_u_e_u_e_s(_3_X). EXAMPLES For examples see the test and benchmark library (directory "tst"). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 80 September 3, 1990 OBJECTS(3X) NAME objects - object oriented programming extension SYNOPSIS #include objects.f83 objects DESCRIPTION This library realizes the popular class-instance model of object oriented programming. The "world" is divided into classes and instances. The classes hold all common information for the instances. This informa- tion is the instance variable fields and the messages an instance can answer. The answer of a message is called a method. A method may call the super class implementation of a message with the prefix word "super". This creates a static binding of the message to the super class. A messages require the object as the top most parameter stack element and will locate an appropriate method at run-time (late- binding). : .class ( object -- ) Displays the name of the class of an object on the current output stream. : .message ( message -- ) Displays the name of the message on the current output stream. May be used by the error message "doesNotUnderstand" which receives a message as parameter. : align ( -- ) Instance variable layout control word. Used to align the next field to an even byte boundary within the definition section of a class. : basicInstanceSize ( class -- num) Returns the instance size in bytes. subclass.field byte ( -- ) Used within the instance variable section of a class definition to create a byte field name. byte <_n_a_m_e> ( object -- addr) The field will require an object and will return the address of the byte within the object. : bytes ( size -- ) Used within the instance variable section of a class definition to create a byte vector field name. <_s_i_z_e> bytes <_n_a_m_e> ( object -- addr) The field will require an object and will return the address of the byte vector within the object. : canUnderstand ( message class -- bool) Returns "true" if the class can understand the message (there exists a method) else "false". 81 OBJECTS(3X) September 3, 1990 : class ( object -- addr) Returns the class address for the object. The class is implemented as a prototype. : dispose-instance ( object -- ) Used in the following form: <_o_b_j_e_c_t> dispose-instance ( -- ) to reclaim memory allocated for an object. The object should not be accessed after this functions. Only objects allocated with the word "new-instance" may be reclaimed. Objects created with the word "instance" should be regarded as global variables. forward doesNotUnderstand ( message object -- ) Forward declared error message. Sent to an object when the message lookup mechanism fails. May be used to implement "proxy" objects. subclass.field enum ( -- ) Used within the instance variable section of a class definition to create a enumerate field name. enum <_n_a_m_e> ( object -- addr) The field will require an object and will return the address of the enumerate within the object. forward initiate ( ... object -- ) This word is called by "new-instance" and "instance" and should be a message used to initiate the newly created object. : instance ( class -- ) Used in the following form: <_c_l_a_s_s> instance <_n_a_m_e> ( -- object) to create a named instance of a class. The message "initiate" is send to the newly created instance. This message must be answered. subclass.field long ( -- ) Used within the instance variable section of a class definition to create a long integer field name. long <_n_a_m_e> ( object -- addr) The field will require an object and will return the address of the long integer within the object. : message ( -- ) Used in the following form: message <_n_a_m_e> ( ... object -- ... ) to create a message. The message may be passed to an object as a normal function call. The top most parameter is always required to be an object. A method for the message is located at run-time giv- ing late binding, and polymorphism. : method ( -- ) Used in the following form within the definition section of a class: method <_m_e_s_s_a_g_e> ( ... object -- ...) ... ; to define a method for the message. The method will receive the object, self, as the first parameter. To pass the message to the 82 September 3, 1990 OBJECTS(3X) superclass the message prefix word "super" may be used. This is common practice in object oriented programming. The method defini- tion should not contain the words "recurse", "tail-recurse", and "exception>" as these require an entry binding. : new-instance ( class -- object) Used in the following form: <_c_l_a_s_s> new-instance ( -- object) to create an instance of a class. The message "initiate" is sent to the newly created instance. This message must be answered or the error message "doesNotUnderstand" is sent to the instance. The object may be reclaimed with the word "dispose-instance". vocabulary objects ( -- ) The object oriented extension vocabulary. Include to the vocabulary search set, "context", to allow programming in the object oriented programming paradigm. subclass.field ptr ( -- ) Used within the instance variable section of a class definition to create a pointer field name. ptr <_n_a_m_e> ( object -- addr) The field will require an object and will return the address of the pointer field within the object. : send ( object message class -- object) Primitive message sending function. Used by the normal message- passing, "message", mechanism to locate and apply a method. : subclass ( superclass -- ) Used in the following form: <_c_l_a_s_s> subclass <_n_a_m_e> { <_i_n_s_t_a_n_c_e-_v_a_r_i_a_b_l_e-_f_i_e_l_d> } { <_m_e_t_h_o_d> } subclass.end to initiate the definition of a class. This definition should con- tain two major sections; the instance variable fields, and the instance methods. All field names will become local to the class. The words "byte", "bytes", "enum", "word", "long" and "ptr" should be used to create instance variable field names. These will require an object pointer and will return the address of the corresponding field. The field should then be manipulated with the memory access functions. The word "align" may be used before a field name defin- ition to align it to an even byte boundary. The method definition section may contain implementations of messages. A method may be viewed as a normal colon definition with the extension that many definitions, methods, for the same name, message, may exist simul- taneous and the selection is performed at run-time (late binding). The method should always receive the object, self, as the top most parameter. The message prefix word "super" may be used to call the super class implementation of a method. This binding is static. The word "this-class" may be used to access the current class. The method may not use the words "recurse", "tail-recurse", and "excep- tions>" as these require an entry binding. 83 OBJECTS(3X) September 3, 1990 : subclass.end ( -- ) Used in the following form: <_c_l_a_s_s> subclass <_n_a_m_e> { <_i_n_s_t_a_n_c_e-_v_a_r_i_a_b_l_e-_f_i_e_l_d> } { <_m_e_t_h_o_d> } subclass.end to finish the definition of a class. Additional methods and fields should not be defined after this word. : super ( -- ) immediate compilation Used in the following form within a method definition: super <_m_e_s_s_a_g_e> to call a method for a message in the superclass. This word should only be used inside of method definitions. : superclass ( class1 -- class2) Returns the address super class of the class. The value is "nil" for a root class. : this-class ( -- class) immediate Returns the address of the current definitions class. Will return "nil" outside of a class definition. subclass.field word ( -- ) Used within the instance variable definition section of a class to create a word integer field name. word <_n_a_m_e> ( object -- addr) The field will require an object and will return the address of the word integer within the object. INTERNALS Private definitions in the _o_b_j_e_c_t_s vocabulary; : allot-instance ( class -- object) private Used in the following form: <_c_l_a_s_s> allot-instance ( -- object) to create an instance of a class. The message "initiate" is sent to the newly created instance. This message must be answered or the error message "doesNotUnderstand" is sent to the instance. The object is allocated from the dictionary area. slot instance-size: ( class -- num) private Slot for a class (prototype) containing the number of byte for an instance of this class. slot instance-variables: ( class -- entry) private Slot for a class (prototype) containing a pointer to the last defined instance variable field entry. The list of variables is terminated by the class itself. : subclass.field ( size -- ) private Use to create instance variable field type names. These field types should only be used within a class definition. 84 September 3, 1990 OBJECTS(3X) variable the-class ( -- addr) private Used within a class definition section to access the address of the current definition class. Outside of the definition section the variable will have the value "nil". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _p_r_o_t_o_t_y_p_e_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. WARNING This library contains forward declared words which should be supplied. Check that your definitions vocabulary comes before the "objects" voca- bulary when defining these words. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 85 PARSER(3X) August 21, 1990 NAME parser - top down parser with backtrack and semantic binding SYNOPSIS #include parser.f83 parser DESCRIPTION Top down parser with backtrack and semantic attributed grammar. Translates string using a grammar to a sequence of semantic actions in forth. variable >break ( -- addr) Pointer to scanner break function. The default function is the parser break function "break-on-special". The parser also supports the forth entry break function "break-on-white-space". variable >buffer ( -- addr) Current buffer position during parsing. Pointer into the "buffer". variable >skip ( -- addr) Pointer to scanner skip function. The default function is the parser skip function "skip-white-space". : bind ( addr -- ) Appends the given parameter as a literal value to the list of semantics. Should be used by "primary" functions to bind scanned data such as numbers, strings, and identifiers. : break-on-special ( addr -- bool) Default break character function for scan. Returns "true" if the current character is a break character. The default function will return "false" if the character is a letter or a digit else true. : break-on-white-space ( addr -- bool) Alternative break character function for scan used by entry to scan for forth words. Returns "true" if the current character in the input buffer is a white space (less or equal to a space character). Used by the parser primary "entry". variable buffer ( -- addr) Parser scanner buffer pointer. May be assigned to an application buffer to parse. symbol empty ( -- symbol) Symbol for basic primary function; <_e_m_p_t_y>. Basic primary function which always returns "true". : end.syntax ( -- ) immediate compilation Marks the end of a syntax rule definition. : end.primary ( -- ) immediate compilation 86 August 21, 1990 PARSER(3X) Marks the end of a primary function. symbol entry ( -- symbol) Symbol for basic primary function; <_e_n_t_r_y>. Basic primary function which returns "true" is the next token is an entry in the current vocabulary search path. The next token may have a vocabulary pre- fix. In this case the token is located in the given vocabulary. The entry pointer is appended as a literal to the list of semantics. symbol eoln ( -- symbol) Symbol for basic primary function; <_e_o_l_n>. Basic primary function which returns "true" when no more tokens exist in the parser buffer. symbol identifier ( -- symbol) Symbol for basic primary function; <_i_d_e_n_t_i_f_i_e_r>. Basic primary function which returns "true" if the next token is an identifier. The string address and length are appended as literals to the list of semantics. : interact ( symbol -- ) Interaction top loop using the parameter symbol as parse goal. The top loop will perform the following operation; read line from input stream, parse the line with the given goal syntax, and if a parse is possible execute the semantic actions. The top loop is repeated until the token "forth" is given. symbol number ( -- symbol) Symbol for basic primary function; <_n_u_m_b_e_r>. Basic primary function which returns "true" if the next token is a number. The value of the number is appended as a literal to the list of semantics. : no-semantic ( -- true) Parser virtual machine instruction for the end of a rule with no semantic function. Will always return "true" and exit the current rule. : non-terminal ( symbol -- [] or [false]) Parser virtual machine instruction for parsing a non-terminal sym- bol. Will continue the execution of the rule if "true" else return to the syntax function. parser ( -- ) The Top Down Parser Virtual Machine definitions vocabulary. Include into the vocabulary search set, "context", to allow access to this library. : parse ( symbol -- [semantics] or [false]) Given a symbol reference, parses the current buffer contents and if parsed the generated list of semantics is returned else false. The list of semantics is a block of code and may be executed with the block function call. : parse" ( symbol -- ) execution 87 PARSER(3X) August 21, 1990 Used in the following form: <_s_y_m_b_o_l> parse" <_p_a_r_s_e _s_t_r_i_n_g> " to give a string to parse. The string is parsed with the given goal syntax symbol and if parsed the semantics actions are called else an error message is given and an abort is performed. : primary ( symbol -- ) Used in the following form: <_s_y_m_b_o_l> primary ( -- bool) ... <_d_e_f_i_n_i_t_i_o_n> ... end.primary to define a primary function. These are used by the parser when a syntax definition is missing or fails to continue the parse pro- cess. The primary function should scan the buffer at the current position and signal to the parser if the next token is accepted or not. The function should return true when accepting the next token and false when rejecting it. The word "bind" should be used to cap- ture data and pass it to the semantic actions. : scan ( -- addr n) Token scanning function. Returns address to token in buffer and length of token. If the buffer contains no more characters a zero length is returned. : semantic ( -- true) Parser virtual machine instruction for appending the succeeding function to the list of semantics. Will always return "true" and exit the current rule. : semantic, ( addr -- ) Appends the given semantic action function to the list of seman- tics. : skip-white-space ( addr1 -- addr2) Default skip character function of scanner. Skips all characters until a character which is greater than blank or null. The parame- ter is the current position in the scanner buffer. The return value is address to the first non-skip character or a null character. struct.type symbol ( -- ) Structure definition of a parser symbol. Used in the following form: symbol <_n_a_m_e> ( -- symbol) to create a symbol which may occur in syntax and primary defini- tions. : syntax ( symbol -- ) Used in the following form: <_s_y_m_b_o_l> syntax ... <parser virtual machine definition> ... end.syntax to generate a grammar rule. The definition should contain the parser virtual machine definitions; "terminal", "non-terminal", "zero-or-one", "zero-or-more", and ended with one of the following; "semantic", and "no-semantic". Each of these functions takes a sym- bol as a parameter. 88 August 21, 1990 PARSER(3X) : terminal ( symbol -- [] or [false]) Parser virtual machine instruction for matching a terminal symbol. Will continue the execution of the rule if "true" else return to the syntax function. : zero-or-more ( symbol -- ) Parser virtual machine instruction for parsing a non-terminal sym- bol zero or more times. Will always continue the execution of the rule. : zero-or-one ( symbol -- ) Parser virtual machine instruction for parsing a non-terminal sym- bol zero or one time. Will always continue the execution of the rule. INTERNALS The _p_a_r_s_e_r vocabulary contains the following private definitions. ptr +entry ( symbol -- addr) private Access field to entry reference in a "symbol" structure. ptr +next ( rule -- addr) private Access field to next rule in syntax list in a "rule" structure. ptr +primary ( symbol -- addr) private Access field to primary function in a "symbol" structure. ptr +rule ( rule -- addr) private Access field to virtual parse machine code for a rule structure. ptr +syntax ( symbol -- addr) private Access field to syntax rule list in a symbol structure. variable >semantics ( -- addr) private Pointer to end of list of semantics in the vector "semantics". : backtrack ( x y -- ) private Backtracks the parser to the state given by the environment block on stack captured by "seize". create interact-buffer ( -- addr) private Internal buffer used for interaction top loop. constant interact-buffer-size ( -- num) private Size of internal buffer used for interaction top loop. : primary ( symbol -- bool) private Executes a symbols primary function. Returns the value from this function if available else "false". : release ( rule x y -- ) private Releases an environment block build by a "seize" call. struct.type rule ( -- ) private 89 PARSER(3X) August 21, 1990 Structure definition of a syntax rule. : rule ( rule -- bool) private Executes the parser virtual machine code definition for a rule. : seize ( rule -- rule x y rule) private Captures the current state of the parser. This environment may be released or used to "backtrack" the parser. create semantics ( -- addr) private List of semantic actions. Collected during the parse and is returned by parse when it succeeds. The list is a compiled block of forth definitions. constant semantics-size ( -- num) private Size of list of semantics. : syntax ( symbol -- bool) private Given a symbol performs the basic top down parsing with the symbols syntax definition as goal. Returns "true" if the syntax parse succeeds else false. create token ( -- addr) private Internal buffer for tokens used by "entry" primary function. constant token-size ( -- num) private Size of internal buffer for token. Used by basic primary function "entry". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _i_n_t_e_r_n_a_l_s(_3_X), _c_o_m_p_i_l_e_r(_3_X), _b_l_o_c_k_s(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be 90 August 21, 1990 PARSER(3X) included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 91 PROTOTYPES(3X) August 20, 1990 NAME prototypes - object oriented extension modeled as prototypes SYNOPSIS #include prototypes.f83 prototypes DESCRIPTION Prototypes are a general form of object oriented programming which allow data and code sharing on any level without dividing the world into "classes" and "instances". A prototype may have slots and methods. Slots hold data values and methods are ways of answering messages. If a proto- type does not contain a requested slot or does not know how to answer a specific message it may delegate the request to another prototype through an inheritance relation. This library supports the definition of prototypes, slots, messages, and methods. It is build on top of the relations extensions by adding an interpreted relation, "inherits", and a delegation function. : .message ( message -- ) Displays the message entry name on the current output stream. : .prototype ( prototype -- ) Displays the prototype entry name on the current output stream. If the prototype does not contain an entry binding the prototype is displayed in the format "prototype#<address>". : .relations ( prototype -- ) Displays the current list of relations associated with a prototype. The list includes all slots, methods, and the inheritance relation. : .slot ( slot -- ) Displays the slot entry name on the current output stream. : -> ( value prototype -- ) immediate Used in the following form: <_v_a_l_u_e> <_p_r_o_t_o_t_y_p_e> -> <_s_l_o_t> to assign a prototype slot. If the slot is not available it is added to the prototypes relations. The assignment is always local to the prototype and does not use the inheritance chain. A proto- type cannot alter the value of an inherited slot without sending a message to the prototype who owns the slot. : inherited ( -- ) immediate compilation Used in the following form: inherited <_m_e_s_s_a_g_e> to send the message to the inherited prototype. The inheritance chain is retrieved at run-time. This allows addition dynamic bind- ing of messages. This word should only be used in a method defini- tion. : parent ( prototype -- addr) 92 August 20, 1990 PROTOTYPES(3X) Returns the value of the inheritance relation. The value may be "nil". : prototype ( parent -- ) Used in the following form: <_p_a_r_e_n_t> prototype <_n_a_m_e> ( -- prototype) to create a prototype variable. Slots and message may be associated with the prototype. Slots are created with the assignment operator. A message may be answered with a "method". The prototype will inherit from the <_p_a_r_e_n_t> prototype. The value "nil" should be used to indicate a root prototype without inheritance. : prototype>entry ( prototype -- entry) Returns a pointer to the vocabulary entry of the prototype. The value may be "nil" of a nameless prototype. vocabulary prototypes ( -- ) The prototypes extension vocabulary. Include to the vocabulary search set, "context", to allow access to this library. : message ( -- ) Used in the following form: message <_n_a_m_e> ( ... prototype -- ... prototype) to define a message type. The message will, at run-time, require the prototype to answer the message as parameter. A "method" for the message is located using the delegation function, "delegate". If a method is found it is applied with the prototype as the first parameter. If a method is not found the forward declared word "unknown-message" is applied with the prototype and message as parameters. This allows implementation of error handling as mes- sages and definition of proxy prototypes. : method ( prototype -- ) Used in the following form: <_p_r_o_t_o_t_y_p_e> method <_m_e_s_s_a_g_e> ( ... prototype -- ...) ... ; to define a prototype method of a message. The method is added to the prototypes relations. The method becomes the new method if a method already exists for the message. The method will always receive the prototype, self, as the first parameter. The method acts as a normal colon definition but it may not contain the fol- lowing words; "exception>", "recurse", and "tail-recurse", as these require an entry binding. : new-prototype ( parent -- prototype) Returns a new nameless prototype with the given parent. The parent value may be "nil" for a root prototype. : slot ( -- ) Used in the following form: slot <_n_a_m_e> ( prototype -- value) to create a slot name. The slot, when used, will require a proto- type as parameter and will return the current value. If the slot cannot be found after delegation the forward declared word "unknown-slot" is applied with the prototype and slot as 93 PROTOTYPES(3X) August 20, 1990 parameters. This allows error handling as a message or as a colon definitions. A slot may be assigned with the prefix operator "->". : this-prototype ( -- prototype) Returns the prototype address. Should be used after the word "pro- totype" as it requires the last entry to be a prototype definition. forward unknown-message ( message prototype -- ) This word is called when the delegation function cannot locate a method for the message for the prototype. This word may be defined as a message or as a colon definition. forward unknown-slot ( slot prototype -- ) This word is called when the delegation function cannot locate a slot for the prototype. This word may be defined as a message or as a colon definition. INTERNALS Private definitions in the _p_r_o_t_o_t_y_p_e_s vocabulary; : (inherited) ( prototype message -- ) Run-time action for the word "inherited". Delegates the message to the parent prototype instead of searching at the prototype itself. true]) private : delegate ( relation prototype -- [relation prototype false] or [value Primitive lookup function. Used to locate slots and methods for a prototype. Extends the relations lookup function "?get-relation" so that relations may be located along the prototypes inheritance chain. item inherits ( -- relation) private The predefined inheritance item. Used by the delegation function, "delegate", and other dependent functions, e.g., "slot" and "mes- sage". variable the-prototype ( -- addr) private Variable containing the method prototype. Bound by the word "method" and used by the word "inherit" to access the current definition prototype. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _r_e_l_a_t_i_o_n_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. WARNING This library contains forward declared words which should be supplied. Check that your definitions vocabulary comes before the "prototypes" vocabulary when defining these words. 94 August 20, 1990 PROTOTYPES(3X) COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 95 QUEUES(3X) August 6, 1990 NAME queues - tile kernel double linked list extensions SYNOPSIS #include queues.f83 queues DESCRIPTION The _t_i_l_e forth kernel word set for support of double linked circular lists. Used by the kernel to maintain the run-time queue of tasks for the multi-tasking extension. : .queue ( queue -- ) Displays information about a queue header or item in the format: queue# <_q_u_e_u_e-_p_o_i_n_t_e_r> succ: <_s_u_c_c-_p_o_i_n_t_e_r> pred: <_p_r_e_d-_p_o_i_n_t_e_r> code ?empty-queue ( queue -- bool) Returns "true" if the queue is empty else "false". Successor pointer points to the queue itself. This definition is also avail- able as forth code for portability to other environments. : ?map-queue ( queue block[item -- bool] -- ) Used in the following form: <_q_u_e_u_e> <_c_o_n_d_i_t_i_o_n_a_l-_b_l_o_c_k> ?map-queue to perform a block of code on each element of the queue until the block returns "true". : ?member-queue ( item queue -- bool) Search for "item" in "queue". If found returns "true" else "false". struct.type QUEUE ( -- ) Structure definition of double linked list. Used as follows to create a new queue header instance: new-struct QUEUE ( -- queue) A named queue header may be created with: QUEUE <_q_u_e_u_e-_n_a_m_e> ( -- queue) Contains two private fields, "+succ" and "+pred". code dequeue ( item -- ) Removes "item" from any queue. Observe this function does not require knowledge about which queue "item" is a member of. This definition is also available as a colon definition for portability of other environments. code enqueue ( item queue -- ) Inserts "item" into "queue" as the new predecessor element. If the "queue" parameter is a queue header "item" is inserted last into the queue. "item" must be a pointer to a "QUEUE" field of a struc- ture or a sub-structure of "QUEUE". This definition is also avail- able as a colon definition for portability of other environments. : map-queue ( queue block[item -- ] -- ) 96 August 6, 1990 QUEUES(3X) Used in the following form: <_q_u_e_u_e> <_b_l_o_c_k> map Calls the parameter code "block" on each item in the queue. vocabulary queues ( -- ) Vocabulary containing double linked circular list extensions. Include into the vocabulary search structure, "context", to gain access to these extensions. : size-queue ( queue -- num) Returns the length of a queue. The queue head is counted. Returns a integer larger than zero. : succ ( queue1 -- queue2) Returns pointer to successor queue item. : pred ( queue1 -- queue2) Returns pointer to predecessor queue item. INTERNALS Private definitions in the _q_u_e_u_e_s vocabulary; ptr +succ ( queue -- addr) private Field of the structure type "QUEUE". Modifiers a queue pointer to access successor pointer in queue structure. ptr +pred ( queue -- addr) private Field of the structure type "QUEUE". Modifiers a queue pointer to access predecessor pointer in queue structure. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be 97 QUEUES(3X) August 6, 1990 included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 98 August 6, 1990 RANGES(3X) NAME ranges - integer range functions library SYNOPSIS #include ranges.f83 ranges DESCRIPTION The _t_i_l_e forth integer range library. Allows definition and manipulation of ranges of integers. Defines a recognition function so that standard range notation may be used, i.e., [<from>..<to>], where <from> and <to> are integer values. struct.type RANGE ( from to -- ) The range defined as a structure type thus structure operations are allowed (e.g. sizeof) and access of the interval range numbers. May be used to create range variables or fields in "structures". The "RANGE" variable may be accessed using the double number memory access functions; "2@", and "2!". The structure type contains two private fields, "+from" and "+to". : range ( from to -- ) Used in the following form to create a range constant: <_f_r_o_m> <_t_o> range <_r_a_n_g_e-_n_a_m_e> ( -- from to) When the range constant is used it will produce the values. Any double variable may used as an integer range if the values are in the right order, "from".."to", and may be accessed and manipulated with the double number stack and memory access functions. vocabulary ranges ( -- ) Integer range extensions vocabulary. Include into the vocabulary search structure, "context", to allow access to these extensions. : ?intersection-range ( from1 to1 from2 to2 -- bool) Returns "true" if there exists an intersection range between the two ranges defined by "from1".."to1" and "from2".."to2" else "false". : ?map-range ( from to block[index -- bool] -- ) Used in the following form: <_r_a_n_g_e> <_c_o_n_d_i_t_i_o_n_a_l-_b_l_o_c_k> ?map Conditional map function on a range. The block is called for each value of the range starting with "from" and ending with "to" until the block returns "true". The block receives the index as a parame- ter and should return a boolean value. : ?member-range ( x from to -- bool) Returns "true" if the value is within the range defined by "from" and "to" else "false". : ?range ( str -- [from to true] or [str false]) recognizer The integer range recognition function. Is called automatically by 99 RANGES(3X) August 6, 1990 "interpret" when a literal is encountered and the "ranges" vocabu- lary is member of the search chain. The recognizer function will return "true" if the parameter string is of the format: [ <_f_r_o_m> .. <_t_o> ] and the relationship between the numbers is correct, i.e., <_t_o> is greater or equal to <_f_r_o_m>. : intersection-range ( from1 to1 from2 to2 -- from3 to3) Given two ranges defined by "from1".."to1" and "from2".."to2" returns their intersection. This function does not check if an intersection exists. This may be done with the word "?intersection-range". : map-range ( from to block[index -- ] -- ) Used in the following form: <_r_a_n_g_e> <_b_l_o_c_k> map-range Map function on a range defined by "from" and "to". The block is called for each value of the range starting with "from" and ending with "to". The block receives the index as a parameter. : size-range ( from to -- num) Returns the size of the range by calculating "to" - "from" + 1. INTERNALS Private definitions in the _r_a_n_g_e_s vocabulary; long +from ( range -- addr) private Returns address to "from" value of a "RANGE" structure. long +to ( range -- addr) private Returns address to "to" value of a "RANGE" structure. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X). EXAMPLES An example showing how to used the integer ranges extensions: #include blocks.f83 #include ranges.f83 blocks ranges [0..15] range small-numbers small-number block[ ( index -- ) . ]; map-range cr 10 [-128..127] ?member-range . cr NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. 100 August 6, 1990 RANGES(3X) COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 101 RATIONALS(3X) August 6, 1990 NAME rationals - rational number library SYNOPSIS #include rationals.f83 rationals DESCRIPTION The _t_i_l_e forth rational number library. Allows definition and manipula- tion of rational numbers. Defines a recognition function so that stan- dard rational notation may be used, i.e., <num>/<denom>, where <num> and <denom> are integer values. The rational number system also includes the numbers "undefined" and "infinity". All rational number functions nor- malize their results to maintain as small numbers as possible. Overflow conditions are not checked. Rational numbers are maintained on the stack as an integer number pair. No extra memory is required for arithmetic operations. Double number stack words may be used to mainipulate the rational number. rational -infinity ( -- num denom) The rational number constant for minus infinity. : 1/r ( num1 denom1 -- num2 denom2) Returns the result of dividing one by the rational number, "num1"/"denom1". : ?r< ( num1 denom1 num2 denom2 -- bool) Returns "true" if the rational number, "num1"/"denom1", is arith- metic less than the rational number, "num2"/"denom2" else "false". : ?r= ( num1 denom1 num2 denom2 -- bool) Returns "true" if the rational number, "num1"/"denom1", is arith- metic equal than the rational number, "num2"/"denom2" else "false". : ?r> ( num1 denom1 num2 denom2 -- bool) Returns "true" if the rational number, "num1"/"denom1", is arith- metic greater than the rational number, "num2"/"denom2" else "false". : ?rational ( str -- [num denom true] or [str false]) recognizer The rational number vocabulary literal recognizer function. Will determinate if the string is a rational number using the syntax "<num>/<denom>", where <num> is an integer and <denom> a positive number. The rational number is normalized using the function, "rnormalize", and the value return with the flag "true". If the string is not a rational number the string is returned with the flag "false" struct.type RATIONAL ( -- ) Used in the following form: RATIONAL <_n_a_m_e> ( -- rational) to create a rational variable. The variable should be accessed with 102 August 6, 1990 RATIONALS(3X) the double number memory access functions, "2@" and "2!". The structure type "RATIONAL" contains two private fields; "+num" and "+denom". : i>r ( x -- num denom) Converts the integer value to a rational number. rational infinity ( -- num denom) Returns the value for the rational number for infinity. : r* ( num1 denom1 num2 denom2 -- num3 denom3) Returns the product of the two rational numbers, "num1"/"denom1" and "num2"/"denom2". The result is always normalized. : r+ ( num1 denom1 num2 denom2 -- num3 denom3) Returns the sum of the two rational numbers, "num1"/"denom1" and "num2"/"denom2". The result is always normalized. : r- ( num1 denom1 num2 denom2 -- num3 denom3) Returns the difference of the two rational numbers, "num1"/"denom1" and "num2"/"denom2". The result is always normalized. : r. ( num denom -- ) Displays the rational number in the standard format, "num"/"denom". If the value is zero or infinity these strings are displayed. : r/ ( num1 denom1 num2 denom2 -- num3 denom3) Returns the quotient of the two rational numbers, "num1"/"denom1" and "num2"/"denom2". The result is always normalized. : r>i ( num denom -- x) Converts the rational number to an integer. The result is trun- cated. : rational ( num denom -- ) Used in the following form: <_n_u_m> <_d_e_n_o_m> rational <_n_a_m_e> ( -- num denom) to create a rational number constant. The rational number is restored when the entry is used. vocabulary rationals ( -- ) The rational number extension vocabulary. Include into the vocabu- lary search set, "context", to allow access of this library. : rnegate ( num1 denom1 -- num2 denom2) Returns the result of negating the rational number, "num1"/"denom1". : rnormalize ( num1 denom1 -- num2 denom2) Normalizes the rational number, "num1"/"denom1", towards zero using greatest common divisor. rational undefined ( -- num denom) The rational number constant for undefined. 103 RATIONALS(3X) August 6, 1990 rational zero ( -- num denom) The rational number constant for zero. The value "0/0" may also be used for zero. INTERNALS Private definitions in the _r_a_t_i_o_n_a_l_s vocabulary; _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 104 August 20, 1990 RELATIONS(3X) NAME relations - experimental library for data modeling as relations SYNOPSIS #include relations.f83 relations DESCRIPTION This library allow data represent in one of the most general forms of data modeling with unrestricted data and code sharing. Data is described as a relations, a triple: (item X relation X value). The library sup- ports some of the common iterators over the relation set. Depending on how the attribute is used the search for the attribute-value may be minimized. This implementation uses association lists where the attribute-values is associated with the item. The items may act as both node with relations and as names of relations. The interface to this library is choosen so that internal implementation details are visible. This allows the library to be implemented in other forms such as hash- tables, mapping tables, trees, etc. : .item ( item -- ) Displays the item entry name to the current output stream. If the item is not bound to a entry the following form is used: "item#<address>". : .items ( -- ) Displays the current list of items to the current output stream. : .relations ( item -- ) Displays the current list of relations for the item on the current output stream. : .values ( item -- ) Displays the current list of attribute-value pairs associated with the item on the current output stream. : ?avail-relations ( relation item -- bool) Returns "true" if the relation is available else "false". : ?get-relation ( relation item -- [relation item false] or [value true]) Returns the value of the relation of the item and "true" if found else this function will return the relation and the item and "false". : ?is-relation ( value relation item -- bool) Returns "true" if the relation has the value given else "false". The values are tested with arithmetric equal. struct.type ITEM ( -- ) Structure type for an item. Used by "item" to create the internals of an item. The item is used both for relational data storage and 105 RELATIONS(3X) August 20, 1990 as an attribute. The words "new-item" and "item" should be used to create "item" words. Contains three private structure fields; "+next-item", "+entry", and "+associations". : item ( -- ) Used in the following form: item <_n_a_m_e> ( -- item) to create an item entry. The <_n_a_m_e> will return the address of the item when used. The item may be used to associate value with and may also be used as a relation. variable items ( -- ) Global variable in the "relations" extension holding the list of defined items (with the word "item"). The latest defined item occurs first in the list. This variable may be accessed and changed to create item sets. : item>entry ( item -- entry) Returns the entry address of the item. This value may be "nil" depending on how the item was created. : get-relation ( relation item -- value) Returns the value of the relation of the item. The value is assumed to exist. If the relation is not found this function will fail and a memory access signal is generated. : map-item ( item block[value relation -- ] -- ) Used in the following form: <_i_t_e_m> block[ ( value relation -- ) ... ]; map-item to apply a block to each relation and value pair associated with an item. The block will receive the relation and its value as parame- ters. : map-items ( block[item -- ] -- ) Used in the following form: block[ ( item -- ) ... ]; map-items to apply a block to each item in the relation set. The block will receive the item as a parameter. May be used to iterate over the item set and extract all items with a certain relation. : map-relation ( relation block[value item -- ] -- ) Used in the following form: <_r_e_l_a_t_i_o_n> block[ ( value item -- ) ... ]; map-relation to apply a block to each item with the given relation. The block will receive the item and the relation value as parameters. The relation may be an item or a number, pointer etc. The typing of the value is up to the application but may also be stored as a rela- tion. : new-item ( entry -- item) Returns a new item with the entry binding. The new item will become nameless if the entry is "nil". : put-relation ( value relation item -- ) 106 August 20, 1990 RELATIONS(3X) Adds the relation and value to the items associations. If the rela- tion is available defined the new value is assigned. If the rela- tion is not available a new relation-value pair is created and appended to the associations. vocabulary relations ( -- ) The relations library vocabulary. Include into the vocabulary search set, "context", to allow access to these extensions. : remove-relation ( relation item -- ) Removes the relation from the items associations. If the relation is not available no operation is performed. INTERNALS Private definitions in the _r_e_l_a_t_i_o_n_s vocabulary; ptr +associations ( item -- addr) private Structure access field of "ITEM" to the list of associations. The value is a pointer to an "ASSOCIATION" structure. ptr +entry ( item -- addr) private Structure access field of "ITEM" to the entry. Used to access the name field of the item. ptr +next-association ( association -- addr) private Structure access field of "ASSOCIATION" to the next association in the list of associations. The value is a pointer to an "ASSOCIA- TION" structure. ptr +next-item ( item -- addr) private Structure access field of "ITEM" to the list of item entries. The value is a pointer to the next "ITEM" structure in the list of items. ptr +relation ( association -- addr) private Structure access field of "ASSOCIATION" to relation of the associa- tion. The value should be a "ITEM" pointer. ptr +value ( association -- addr) private Structure access field of "ASSOCIATION" to value of a relation. The value is store in a "cell". struct.type ASSOCIATION ( -- ) private Structure type for an association. The association is a triple list element with three private fields; "+next-association", "+rela- tion", and "+value". : associate ( relation association -- addr) private Primitive lookup function used by "get-relation", "?get-relation" and "put-relation" to locate an "ASSOCIATION" in the association list. Returns the address of the value if the relation is found. If the relation is not found "nil" is returned. 107 RELATIONS(3X) August 20, 1990 SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 108 August 7, 1990 SETS(3X) NAME sets - vector represented sets definitions SYNOPSIS #include sets.f83 sets DESCRIPTION Library for sets represented as vectors. The set is a terminated by a "nil" pointer. This set representation is mainly used for small sets of entry pointer and other non-zero values. "nil" and zero cannot be members of a set. The vocabulary search chain is represented as a set. : .set ( set -- ) Assuming that the set contains elements that are vocabulary entries this function will display the set in normal set notation: { <_e_n_t_r_i_e_s> } The format is equal to the input notation constant sets. : ?empty-set ( set -- bool) Returns "true" if the set is empty else "false". : ?map-set ( set block[element -- bool] -- ) Conditional set iterator. Calls the conditional block on each ele- ment in the set while the block returns "false". The iterator is terminated if the block returns "true" or if the block is empty. The conditional block will receive the element as a parameter and should return a boolean flag. : ?member-set ( element set -- bool) Returns "true" if the element is a member of the set else "false". : append-set ( element set -- ) The element is appended to the set. If the element is already a member of the set no operation is performed. An element cannot occur more than once in a set. : apply-set ( set -- ) Assuming all elements of the set are entry pointers this words will "execute" all elements once. : empty-set ( set -- ) Assign the set as the empty set. : intersection-set ( set1 set2 -- ) Remove elements in both "set1" and "set2" from "set2". "set2" becomes the intersection of the sets. : map-set ( set block[element -- ] -- ) Set iterator function. Call the block on each element in the set. The block will receive the element as a parameter. 109 SETS(3X) August 7, 1990 : remove-set ( element set -- ) Remove the element from the set. If the element is not a member of the set no operation is taken. : set ( size -- ) Used in the following form: <_s_i_z_e> set <_s_e_t-_n_a_m_e> ( -- set) to create of set for "size"-1 elements. Each element is "cell" bytes and may contain a number or pointer. vocabulary sets ( -- ) The vector represented set extension vocabulary. Include into the vocabulary search set, "context", to allow access of this library. : size-set ( set -- num) Returns the number of element in the set. : union-set ( set1 set2 -- ) The elements of "set1" are appended to the "set2". "set2" becomes the union of the sets. : { ( -- ) execution Used in the following form: { <_e_n_t_r_i_e_s> } ( -- set) to mark the beginning of a constant set of vocabulary entries. : } ( -- set) immediate Used in the following form: { <_e_n_t_r_i_e_s> } ( -- set) to mark the end of a constant set of vocabulary entries. INTERNALS The _s_e_t_s library contains the following internal function to search a set. : search-set ( element set -- [addr1] or [element addr2 false]) Searches the set for the element. Returns the address, "add1", of the element if found else the element together with the last address, "addr2", and the flag, "false", is returned. Used to implement the functions "add-set", "remove-set", "?member-set" and "intersection-set". SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _b_l_o_c_k_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entry is indicated together with the parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are 110 August 7, 1990 SETS(3X) preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 111 STACKS(3X) August 1, 1990 NAME stacks - vector representation of stacks SYNOPSIS #include stacks.f83 stacks DESCRIPTION Library for stacks represented as a vector. This library allows defini- tion and manipulation of "cell" width stacks. Provides functions for overflow and empty checking. Applications are required to check stack consistency with these functions. : .stack ( stack -- ) Displays the contents of a stack in the following form: stack# <_s_t_a_c_k-_a_d_d_r_e_s_s> [ <_s_t_a_c_k-_d_e_p_t_h> ] / <_t_o_p> / ... / <_b_o_t_t_o_m> : ?empty-stack ( stack -- bool) Returns "true" if the stack is empty else "false". : ?full-stack ( stack -- bool) Returns "true" if the stack is full else "false". : ?map-stack ( stack block[element -- bool] -- ) Conditional iterator for stacks. The parameter conditional block on each element on the stack starting with the top of stack and preceding towards the bottom of the stack. The conditional block should return a boolean flag for each call. The iterator is ter- minated when the block returns "true". struct.type STACK ( size -- ) Used in the following form: <_s_i_z_e> STACK <_s_t_a_c_k-_n_a_m_e> ( -- stack) to create a stack variable. May also be used to create a unnamed stack instance with the "structures" library function "new-struct". In this case include the "structures" library and use the following form: <_s_i_z_e> new-struct STACK ( -- stack) The top of stack pointer is stored first in the "STACK" structure. <_s_t_a_c_k> @ @ ( -- element) This allows the top of stack element to be accessed indirectly through the stack variable. This action will copy the top of the stack to the forth parameter stack and not effect the internal stack pointers. : depth-stack ( stack -- num) Returns the stack depth. The return value represents the number of "pop" call that may be performed before the stack is empty. : empty-stack ( stack -- ) Removes all elements from the stack by putting the stack top to be the stack bottom. The stack depth becomes zero and the stack 112 August 1, 1990 STACKS(3X) becomes empty. : map-stack ( stack block[element -- ] -- ) Stack iterator function. Calls the parameter block for each element in the stack starting with the top of stack and continues towards the bottom of the stack. : pop ( stack -- element) Removes the top element for the stack and returns this value. This function will not check if the stack is empty. Applying this func- tion on an empty stack will leave the stack in an error state. : push ( element stack -- ) Appends the element to the top of the stack. This function will not check if the stack is full. Applying this function on an empty stack will leave the stack in an error state. : size-stack ( stack -- num) Return the maximum number of elements that the stack can contain. vocabulary stacks ( -- ) Vocabulary containing the stack extensions. Include into the voca- bulary search structure, "context", to allow access of this library. INTERNALS Private definitions in the _s_t_a_c_k_s vocabulary; ptr +top ( stack -- addr) private Access field in "STACK" structure to pointer to top of stack. long +bytes ( stack -- addr) private Access field in "STACK" structure to size of stack area in bytes. The total size of a stack in bytes is the sum of the "STACK" struc- ture and this field. The size of the "STACK" header may be accessed with the function "sizeof" in the "structures" library. ptr +bottom ( stack --- addr) private Access field in "STACK" structure to pointer to bottom of stack. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X), _s_t_r_u_c_t_u_r_e_s(_3_X), _b_l_o_c_k_s(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. 113 STACKS(3X) August 1, 1990 Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 114 September 7, 1990 STRING(3X) NAME string - tile kernel null-terminated string functions SYNOPSIS string DESCRIPTION The _t_i_l_e forth kernel support word set for null-terminated strings. Used by the kernel to maintain strings in vocabularies, etc. Strings are not allocated from the forth dictionary. code " ( -- str) immediate Used in the following form: " <_a_n_y-_s_t_r_i_n_g> " to compile a string literal. A string is not bounded by any size as it is null terminated. A double quote character cannot be part of the string. code $print ( str -- ) Displays a string on the current output device. code $allot ( n -- str) Allocates storage for a string of max length "n". The string may be reclaimed with the function "$free". code $cat ( str1 str2 -- ) Concatenates "str2" to "str1" and returns the pointer to "str2". "str2" is assumed to have space for "str1" and should have a minimum length of both strings. code $dup ( str1 -- str1 str2) Returns copy of the parameter string. The copy is equivalent to the parameter but is allocated to another memory area. The copy should be reclaimed with the function "$free". code $equal ( str1 str2 -- bool) Compares the two strings and returns "true" if they are equal else "false". code $free ( str -- ) Returns allocated string storage to the run-time heap. code $length ( str -- num) Returns the length of the string not counting the null character terminating the string. A string may have zero length. code (") ( -- str) compilation Compiled run-time action for string literal. Pushes a pointer to the inline string onto the parameter stack. Compiled by the word """. vocabulary string ( -- ) Vocabulary containing the null-terminated string definitions. 115 STRING(3X) September 7, 1990 Include into the vocabulary search structure, "context", to allow access to these extensions. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 116 August 6, 1990 STRUCTURES(3X) NAME structures - aggregated data definitions SYNOPSIS #include structures.f83 structures DESCRIPTION Allows composition of data field description to build structures. A basic language extension library in the _t_i_l_e forth kernel and used throughout the source code library to describe data structures. The "structures" package extends the traditional "record" or "structure" concept and allows initialization and high level management code to be defined together with the structure itself. : align ( -- ) Used within a structure type field definition section to align the current field address to an even address. : as ( -- struct.type) immediate Used in the following form: as <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> ( -- struct.type) Returns the address of the body of the structure type information. This address may be passed to the structure instance initialization function, "initiate". : assign ( x y -- ) immediate Used in the following form: _x _y assign <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> or _x _y assign <_p_r_i_m-_t_y_p_e-_n_a_m_e> Assigns the structure or primitive pointed to by "y" the value of "x". The primitive types are equivalent to the structure type field names, "byte", "word", "long", "ptr" and "enum". struct.field byte ( -- ) Used in the following form: byte <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2) within a structure type definition section to create an access field name to a byte. : bytes ( n -- ) Used in the following form: <_n_u_m_b_e_r> bytes <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2) within a structure type definition section to create a field access name to a given <_n_u_m_b_e_r> of bytes. struct.field enum ( -- ) Used in the following form: enum <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2) within a structure type definition section to create a field access name to an enumerate. The size of an enumerate field is four bytes. 117 STRUCTURES(3X) August 6, 1990 : initiate ( addr struct.type -- ) Used in the following form: <_i_n_s_t_a_n_c_e> as <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> initiate Take a pointer to a memory area and initializes it according to the initialization code for the structure type given as the second parameter. Parameters to this code section can be passed as usual on the parameter stack. struct.field long ( -- ) Used in the following form: long <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2) within a structure type definition section to create a field access name to a long number. The size of a long is four bytes. : new-struct ( -- addr) immediate Used in the following form: new-struct <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> ( -- addr) to allocate and initialize an instance of a structure type. A pointer to the instance is returned. The instance is not bound to any variable. : not-equal ( x y -- bool) immediate Used in the following form: _x _y not-equal <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> or _x _y not-equal <_p_r_i_m-_t_y_p_e-_n_a_m_e> to compare two structure instances. The primitive types are equivalent to the structure type field names, "byte", "word", "long", "ptr" and "enum". struct.field ptr ( -- ) Used in the following form: ptr <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2) within a structure type definition section to create a field access name to a pointer. The size of a pointer is four bytes. : sizeof ( -- num) immediate Used in the following forms: sizeof <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> or sizeof <_p_r_i_m-_t_y_p_e-_n_a_m_e> Returns the size, in bytes, of a structure or primitive type. The primitive types are "byte", "word", "long", "ptr" and "enum". : struct ( -- ) Used in the following form: struct <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2) within a structure type definition section to create a field access name to a structure. The structure is not initialized automatically by the structure type. This should be performed by the initializa- tion code of the structure type it is a part of. This may be per- formed with the words "as" and "initiate". Remember to pass neces- sary parameters to the initialization code. 118 August 6, 1990 STRUCTURES(3X) : struct.does ( addr -- ) immediate compilation Used within a structure type definition section to define the end of the structure layout or initialization code and the beginning of the instance action code. At run-time, performed for entry bounded (named) instance, the code receives a pointer to the instance as parameter. : struct.end ( -- ) immediate Used to terminate a structure type definition. : struct.init ( addr -- ) Used within a structure type definition section to terminate the structure layout and the beginning the definition of the initiali- zation code section. At run-time the code receives a pointer to the instance as a parameter. : struct.type ( -- ) Used in the following forms: struct.type <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> ( ... -- ) <_s_t_r_u_c_t-_t_y_p_e-_l_a_y_o_u_t> struct.init ( ... addr -- ...) <_i_n_i_t_i_a_l_i_z_a_t_i_o_n-_p_a_r_t> struct.does ( ... addr -- ...) <_i_n_s_t_a_n_c_e-_p_a_r_t> struct.end and then: <struct-type-name> <_i_n_s_t_a_n_c_e-_n_a_m_e> Starts the definition of a structure type. The layout section <_s_t_r_u_c_t-_t_y_p_e-_l_a_y_o_u_t> may contain the words; <_n> bytes <_f_i_e_l_d-_n_a_m_e>, allocates "n" bytes, byte <_f_i_e_l_d-_n_a_m_e>, a byte, word <_f_i_e_l_d-_n_a_m_e>, a word, long <_f_i_e_l_d-_n_a_m_e>, a long, ptr <_f_i_e_l_d-_n_a_m_e>, a pointer, enum <_f_i_e_l_d-_n_a_m_e>, an enumerative, and struct <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> <_f_i_e_l_d-_n_a_m_e>, a structure. To align a field to even address use "align". The initialization code receives a pointer to the block to initialize and any additional parameters. Thus additional memory may be allocated directly after the block. If the structure con- tains structure fields these should be initialized by the initiali- zation code. For this "as" and "initiate" are used; <_i_n_s_t_a_n_c_e> as <_s_t_r_u_c_t-_t_y_p_e-_n_a_m_e> initiate. The normal action performed by a instance of a structure type is to return the address to the instance. The optional "struct.does" part redefines the normal action of a created structure block. It receives a pointer to the instance as parameter and any additional parameters. The sections "struct.init" and "struct.does" are optional. vocabulary structures ( -- ) Vocabulary for structure type extensions. Include into the vocabu- lary search structure, "context", to allow use of structures and description of aggregated data structures. : this ( -- addr) Returns the compilation address of the latest defined word. 119 STRUCTURES(3X) August 6, 1990 struct.field word ( -- ) Used in the following form: word <_f_i_e_l_d-_n_a_m_e> ( addr1 -- addr2) within a structure type definition to create a field access name to a word. The size of a word is two bytes. INTERNALS Private definitions in the _s_t_r_u_c_t_u_r_e_s vocabulary; field +size ( struct.type -- addr) private Field for accessing the size of a structure type. This field is a long containing the number of bytes to allocate for an instance of the structure type. field +initiate ( struct.type -- addr) private Field for accessing the initialization code of a structure type. This field is a "ptr" containing a pointer to the initialization code for the structure type. A zero value, "nil", indicates that the structure type does not perform initialization. : struct.field ( bytes -- ) private Used in the following form: <_b_y_t_e_s> struct.field <_f_i_e_l_d-_t_y_p_e-_n_a_m_e> to create additional field types other than "byte" etc. : make-struct ( struct.type -- addr) private Given a pointer to a structure type information block, as generated by "as", allocates memory in the dictionary and initializes it. Returns a pointer to the created instance. SEE ALSO _t_i_l_e(_1), _f_o_r_t_h(_3_X). EXAMPLES An example showing how to defined a list structure: struct.type LIST ( -- ) ptr +next ( list -- addr) struct.init ( list -- ) nil swap +next ! struct.end sizeof LIST . new-struct LIST constant x LIST y NOTE The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect. The "structures" library optimizes the first field so that access becomes an immediate word with no effect. The most common accessed field should be placed first in a "structure" definition. 120 August 6, 1990 STRUCTURES(3X) COPYING Copyright (C) 1990 Mikael R.K. Patel Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the ori- ginal English. AUTHOR Mikael R.K. Patel Computer Aided Design Laboratory (CADLAB) Department of Computer and Information Science Linkoping University S-581 83 LINKOPING SWEDEN Email: mip@ida.liu.se 121